Last change: 31-05-2004


**** Settings in sphere.ini **************************************************************** 
NOTE :	EF flags change from version to version, so make SURE you're using only the EF
	flags you want, if any.

OptionFlags=	// Flags for options that affect server behaviour but not compatibility
	00000001	// OF_Magic_IgnoreAR
	00000002	// OF_Magic_CanHarmSelf
	00000004	// OF_Magic_StackStats		 (Do NOT set this yet)
	00000008	// OF_Skill_DiffFirst
	00000010	// OF_Archery_CanMove
	00000020	// OF_Magic_PreCast
	00000040	// OF_Items_AutoName
	00000080	// OF_FileCommands
	00000100	// OF_NoItemNaming
	00000200	// OF_NoHouseMuteSpeech
	00000400	// OF_SkipUndefMsgs
Suggested value: none
Default value:	OptionFlags=00

Experimental=	// Flags for options that affect server behaviour and which might affect compatibility
	00000001	// EF_DiagonalWalkCheck
	00000002	// EF_UNICODE			 (Don't use this on Linux, server will crash)
	00000004	// EF_CanSeeLOS
	00000008	// EF_Scripts_Ret_Strings
	00000010	// EF_New_Triggers
	00000020	// EF_New_Maps
	00000040	// EF_Scripts_Parse_Verbs
	00000080	// EF_Intrinsic_Locals
	00000100	// EF_Allow_Override
	00000200	// EF_Item_Strict_Comparison
	00000400	// EF_No_Pause_Packet
	00001000	// EF_WalkCheck
	00002000	// EF_AgeOfShadows
	00004000	// EF_DiagonalLOSCheck
Suggested value: Experimental=0404
Default value:	Experimental=00

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


**** 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 <eval 1+1>".

- 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



**** 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)



**** 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.

**** 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 for R3, which already has these files.








