Last change: 08-08-2005 **** The FILE obj ************************************************************************** FILE object permit the manipulation of a file. For the momnet is limited to one file at time but if the test goes well a FILE[x] will be added. To access file function you should use FILE.x or . Some of the function/props can be used only when a file is opened, if they're usable everytime will be signaled with a (*). MODE.APPEND (r/w)(*) = File to open in append mode (this override read and write flag) MODE.CREATE (r/w)(*) = File to open need to be created or overwrited (this override append, read and write flag) MODE.READFLAG (r/w)(*) = File to open in read only mode (the file should already exist). MODE.WRITEFLAG (r/w)(*) = File to open in write only mode (the file should already exist). MODE.SETDEFAULT (w)(*) = File object with Append mode on. OPEN (r) = Open a file. Return true if opened. Ex: INUSE (r)(*) = Check if FILE obj is in use. ISEOF (r) = Check if we're at the end of file. LENGTH (r) = Return the length of file. POSITION (r) = Position of the r/w pointer in the file. READBYTE (r) = Read n bytes from file and return them as string. Ex: READCHAR (r) = Read one byte from file and return it as number. READLINE (r) = Read a line from the file. Accept as argument the line to read. It doesn't alter the position of the r/w pointer in the file. Ex: will read the 5th line of the file. Special case is that'll return the last line. SEEK (r) = It'll move th postion of the r/w pointer at the specified position. Special cases are (move to begin of file) and (move to end) WRITE (w) = Write a string to the file. WRITECHR (w) = Write a char to the file. The char must be inputted with it's ascii value. WRITELINE (w) = Write a string with \n at the end. FILELINES (r)(*) = Return the number of lines contained in a file. Usage FILEPATH (r) = Return filapath+filename of the file opened CLOSE (w) = Close the file currently opened. DELETEFILE (w)(*) = Delete the file supplied as argument. Warning: if the file to delete is the one opened, it'll be not deleted. FLUSH (w) = Flush the buffers associated to the file. Use it at your own risk. **** Settings in sphere.ini **************************************************************** Please review default sphere.ini, especially the OptionFlags= and Experimental= settings with it comments. They DO CHANGE from version to version, thus make SURE that you are using the values you really need. Features= // Flags for options that affect the clients upon connection // 0001 - (T2A) enables chatbutton // 0002 - (LBR) enables LBR sound (plays MP3s instead of MIDI) // 0004 - (T2A) enables T2A update // 0008 - (LBR) enables LBR update (shows monsters) Suggested value: Features=0E Default value: Features=05 FeaturesLogin= // Flags for options that affect AoS clients upon connection (Only with EF_AgeOfShadows) // Send/Request Logout = 002 // One char only (Siege) = 004 // Npc Menu Popup = 008 // Unknown = 010 // Tooltip/Fight Books = 020 Suggested value (if AoS is enabled): FeaturesLogin=028 Default value: FeaturesLogin=00 NOTE: Do not enable AOS features if you plan that T2A/LBR clients will be used by clients of your server. **** Things to pay attention in scripts ****************************************************** - RETURN values Make sure you include an "eval" in your return, wherever you're not returning a plain number, a defname or a string. Instead of doing "return 1+1" do "return ". - NEWNPC, NEWITEM, NEWDUPE You can now call these verbs from within item triggers, and the new object can be referenced via "NEW". When using these on characters, ACT will also be changed. You can use SERV.NEWNPC, SERV.NEWITEM and SERV.NEWDUPE anywhere, and only NEW will be changed. Preferably, always include "SERV." when using these commands. Example (simple trigger for an item that gives gold when dclicked): ON = @DClick SERV.NEWITEM i_gold NEW.AMOUNT 3 NEW.BOUNCE **** Skill difficulties and ACTDIFF. ******************************************************** For most triggers where a skill is involved, ACTDIFF can be used to read/modify the current difficulty. ACTDIFF makes sense wherever ACTION makes sense, seeing as it is associated to the difficulty of performing an action. ACTDIFF has no meaning in @SkillStart, because the difficulty for a skill is calculated afterwards. You can enable the OF_Skill_DiffFirst, to make @SkillStart come first. This has the (only known) sideffect of making @SpellCast come before @SkillStart, as is the usual. @HitMiss is another trigger in which you can change ACTDIFF to a value equal or above 0 to hit an otherwise failing blow. The way sphere interprets ACTDIFF is interesting. It calculates the difficulty, and if the character fails the chance roll against that difficulty, ACTDIFF becomes -ACTDIFF, meaning that you can always find out the initial difficulty, even on a failure. Settinf ACTDIFF to 0 always succeeds. ACTDIFF above your skill fails. **** TRIGGERS: ******************************************************************************** "IN" refers to arguments supplied by the server. OUT refers to values read back by the server, so that changing them within the trigger actually changes some hard-coded behaviour. RET refers to the return value and its effect. Note that there are 3 possible return values: return 1 RET_TRUE Cancel return 0 RET_FALSE Succeed return 2 RET_DEFAULT ( usually the same as return 0 ). It's also the same as "return2", it's the "default return". Unless otherwise specified it does the same as "return 0". If something is specified for "return 0", then "return" is different in that it does the default action. **** CHARACTER TRIGGERS ****** @GetHit IN: argn1 Damage being applied. argn2 Type of damage (see damage type flags). OUT: argn1, argn2 RET: 1 No damage is applied, cancels the action. @HitTry IN: argo Weapon used. RET: 1 Cancel action, hit fails. @HitMiss IN: argo Weapon used. RET: 1 Silently misses (no message is shown). Notice that changing ACTDIFF to >= 0 makes the blow succeed. @Hit IN: argo Weapon used. argn1 Damage being applied. OUT: argn1 RET: 1 Hit is cancelled, damage not applied, @GetHit doesn't get called, etc. @PersonalSpace IN: argn1 Stamina required to push target aside. OUT: argn1 RET: 1 Fails to push target aside, movement fails, stamina is unnafected. 0 Default action, but show no message. @SpellCast, @Start ( [SPELL x] section ) IN: argn1 Spell being cast. argn2 Difficulty to cast. If OF_Skill_DiffFirst, this value is passed to @SkillStart (and only then to ACTDIFF). argn3 DELAY for the spell, in ticks (10 = 1second). argo Item the spell is being cast from (see @SpellSelect) OUT: argn1, argn2, argn3 RET: 1 The spell fails. @SpellEffect, @Effect ( [SPELL x] section ) IN: argn1 Spell number. argn2 Skill level at which the spell is being cast (power of spell). argo Item the spell is being cast from (see @SpellSelect) OUT: argn1, argn2 RET: 1 Cancels the action, no spell effect takes place. 0 For spells with SPELLFLAG_SCRIPTED: succeeds the action, but no (hardcoded) effect takes place. Otherwise, works like 2 2 Hardcoded effect @Fail ( [SPELL x] section ) IN: argn1 Spell number. argo Item the spell is being cast from (see @SpellSelect) RET: 1 Spell fails with no fizzle and no reagents are consumed. 0 Succeeds the action, but no (hardcoded) effect takes place 2 Hardcoded effect @Select ( [SPELL x] section ) IN: argn1 Spell being cast. argn2 Mana being used. argn3 1 if this is just a test (as in cancast) or 0 if actually casting a spell - this is called twice (once before the spell starts and once after it is successful, with different argn3 values). argo Object the magic is being cast from. It's either the character itself or an item like a wand scroll, etc. OUT: argn1, argn2 RET: 1 The spell can't be selected. 0 The spell can be selected, and no further tests are performed. 2 Default (the spell can be cast if all normal tests are successful) @Success ( [SPELL x] section ) IN: argn1 Spell number. argn2 Skill level at which the spell is being cast (power of spell). argo Item the spell is being cast from (see @SpellSelect) OUT: argn2 RET: 1 Cancels the action, the spell fails. NOTE: In @Success ( [SPELL x] section ), both SRC and the default object are the caster, one has to refer to SRC.ACT get the affected object. @UserSkills IN: argn1 Number of skill being updated, or -1 for the skill list window. RET: 1 No update is performed. @SkillFail, @Fail ( [SKILL x] section) RET: 1 Do not perform a skill gain check for failure. @SkillAbort, @Abort ( [SKILL x] section) This is a new trigger, that is fired whenever a skill didn't reach the point of completion, where either @Fail or @Success would be fired. This can happen if the someone starts a skill before finishing the previous, if ACTION=-1 is set or if the situation changes (eg, suddenly you lack reagents while making a potion - it doesn't count as @Fail, it's @Abort). Aborted skills don't yield a chance to gain due to failure. This alone solves many abuse situations. RET: 1 Silently abort the skill, do not perform the typical events associated with a skill going wrong (e.g., in the case of Magery, doesn't show the fizzle effect). @SkillGain, @Abort ( [SKILL x] section) IN: argn1 Skill number. argn2 Chance to gain (from the SKILL section parameters) argn3 Skill cap for this skill. OUT: 1 Do not gain skill (obviously, you can roll against the chance in argn1 and raise the skill yourself). NOTE: ACTDIFF was the difficulty for using the skill. If negative, then the skill failed and this is a gain due to failure. @NPCLookAtItem (needs EF_New_Triggers activated) IN: argo Item being looked at RET: 1 Do not see the item, do not look at other items 0 Do not see the item, look for other items as default 2 default (see the item, look for other items) @NPCLookAtChar (needs EF_New_Triggers activated) RET: 1 Do not see the character, do not look at other characters 0 Do not see the character, look at other characters as default 2 default (see the character, look for other characters) @NPCActFight (needs EF_New_Triggers activated) IN: argn1 distance argn2 motivation (if motivation is below 0, the NPC will attempt to flee) OUT: argn1, argn2 RET: 1 Do nothing this swing 0 default, but skip hardcoded actions (breath/throwing) 2 default Note: After this trigger, the NPC will attempt to do hardcoded skills (breath/throwing), then it will try to use Magery, then Archery, and if it isn't appropriate to use either, use melee combat @NPCActFollow (needs EF_New_Triggers activated) IN: argn1 fleeing? 0/1 argn2 max distance argn3 forcedistance OUT: argn1, argn2, argn3 RET: 1 stop following 0 don't follow at this time, but do not stop following (useful for ranged combat) 2 default NOTE: This trigger listing may appear inaccurate - please read up REVISIONS.TXT to check if some alterations were made to them. **** ITEM TRIGGERS ****** @Step, @ItemStep IN: argn1 1 if standing, 0 if moving into position RET 1 Block movement @DropOn_Item, @ItemDropon_Item IN: argo Item where the item with the trigger is being dropped on. OUT: 1 Do not drop, bounce the item back (if no container is set within script) @DropOn_Char, @ItemDropon_Char IN: argo Item being dropped on the character OUT: 1 Do not drop, bounce the item back (if no container is set within script) @DropOn_Self, @ItemDropon_Self IN: argo Item being dropped on the item with the trigger. OUT: 1 Do not drop, bounce the item back (if no container is set within script) NOTE: This trigger listing may appear inaccurate - please read up REVISIONS.TXT to check if some alterations were made to them. **** OTHER TRIGGERS ****** @ResourceTest // for REGIONRESOURCE sections This trigger is called once for every resource listed in a REGIONTYPE, to check if the player (SRC) can get it. It is called only if the player meets the SKILLMAKE requirements for the item set in REAP. OUT: 1 Ignore the resource (works as if the resource isn't in the REGIONTYPE list) @ResourceFound // for REGIONRESOURCE sections This trigger is called after a resource has been selected and the resource bit has been created. IN: argo resource gem OUT: 1 Remove the resource bit and return as if no resource was found in the spot. Notes: If you .REMOVE the ARGO, you'll remove the resource bit, and thus the spot will be useable again. Otherwise, the resource bit will stay there, with amount set to 0, to specify there is no resource there (until it decays due to its own REGEN). This also yields different error messages. NOTE: This trigger listing may appear inaccurate - please read up REVISIONS.TXT to check if some alterations were made to them. **** Stuff you might need in scripts ************************************************************ This is a set of flags that you might find in static tiles, in statics(n).TILEFLAGS: [DEFNAME tile_flags] // by Shadowlord tilef_background 01 // No idea. None whatsoever. Maybe it's the blackness. tilef_weapon 02 // I smack thee with this here ... club? tilef_transparent 04 // Yeah. So we can see through it? tilef_translucent 08 // Okay... tilef_wall 010 // Hey look, we can't walk through it! tilef_damaging 020 // Lava, perhaps? Fires, hmm! tilef_impassable 040 // Mountains and stuff, I'll wager. tilef_wet 080 // Water? Or mud? Or a slick road in a rainstorm? Probably the first. tilef_unknown 0100 // Uh... tilef_surface 0200 // Tables or something? tilef_bridge 0400 // I wonder why they'd have a flag for that. tilef_stackable 0800 tilef_window 01000 // So we can see/shoot out? tilef_noshoot 02000 // ? We can't shoot out or something? So, like a glass window maybe? tilef_prefixA 04000 // A card tilef_prefixAn 08000 // An apple tilef_internal 010000 // hair, beards, etc tilef_foliage 020000 // Probably bushes and tree leaves and stuff. tilef_partialHue 040000 // semi-glowy? tilef_unknown_1 080000 // Well, gee. I should see if it's used on anything... tilef_map 0100000 // Sounds good to me. tilef_container 0200000 // They flag these!? tilef_wearable 0400000 // Omigod! tilef_lightSource 0800000 // I'm getting tired of typing repetitive shiznit now. tilef_animated 01000000 // Like fire again. And stuff. Those spinny propeller thingies! tilef_noDiagonal 02000000 // !?!???!!? tilef_unknown_2 04000000 // I really hope some of these unknowns are n/w/s/e facing flags. tilef_armor 08000000 // Armor, okay, so does that count shields? Hmmm? tilef_roof 010000000 // "Don't fall through me!" Or why isn't it just flagged surface or something? tilef_door 020000000 // Okay... tilef_stairBack 040000000 // Don't we have stairs that go forward or left too? This could cover both... tilef_stairRight 080000000 // Well, whatever, you can climb them, so, hey... Good use for a This is a set of flags that you can find in the CAN section of items. Some are derived from the flags above, although they are independant and affect only dynamic items. The comments on these were taken out of the source code, and I wouldn't rely on them. I'll replace them as I find better ones. [DEFNAME can_i_flags] CAN_I_DOOR 00001 // Is a door UFLAG4_DOOR CAN_I_WATER 00002 // Need to swim in it. UFLAG1_WATER CAN_I_PLATFORM 00004 // we can walk on top of it. (even tho the item itself might block) UFLAG2_PLATFORM CAN_I_BLOCK 00008 // need to walk thru walls or fly over. UFLAG1_BLOCK CAN_I_CLIMB 00010 // step up on it, UFLAG2_CLIMBABLE CAN_I_FIRE 00020 // Is a fire. Ussually blocks as well. UFLAG1_DAMAGE CAN_I_ROOF 00040 // We are under a roof. can't rain on us. UFLAG4_ROOF CAN_I_PILE 00100 // Can item be piled UFLAG2_STACKABLE (*.mul) CAN_I_DYE 00200 // Can item be dyed UFLAG3_CLOTH? (sort of) CAN_I_FLIP 00400 // will flip by default. CAN_I_LIGHT 00800 // UFLAG3_LIGHT CAN_I_REPAIR 01000 // Is it repairable (difficulty based on value) CAN_I_REPLICATE 02000 // Things like arrows are pretty much all the same. **** AREA / ROOM changes **************************************************************************** Areas / rooms can now be supplied in a different format, similar to ITEMDEF and CHARDEF: [AREADEF defname] NAME = ... This allows the server to identify each area by an unique name. If you want to convert your existing areas to this new format, the process is simple. 1) Launch the server as normal 2) In the console, type "d a" (without the ") 3) A new file, "map_all.scp" should now be created, copy it to the scripts folder. 4) Shutdown the server. Edit spheremap.scp and delete all ROOM/AREA sections, leaving only MOONGATES and TELEPORT sections. 5) Rename spheremap.scp (now only with teleporter/moongate data) to spherepoints.scp and rename map_all.scp to spheremap.scp. 6) Add an entry regarding spherepoints.scp to spheretables.scp Alternatively, you can download the Script Pack, which already has these files.