Last change: 29-12-2003


**** 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
	0001		// OF_Magic_IgnoreAR
	0002		// OF_Magic_CanHarmSelf
	0004		// OF_Magic_StackStats			(Do NOT set this yet)
	0008		// OF_Skill_DiffFirst
	0010		// OF_Archery_CanMove
	0020		// OF_Magic_PreCast

Experimental=	// Flags for options that affect server behaviour and which might affect compatibility
	0001		// EF_DiagonalWalkCheck
	0002		// EF_UNICODE
	0004		// EF_CanSeeLOS
	0008		// EF_ReturnString
	Suggested value: EXPERIMENTAL=01



**** 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.
  NOTE:			In @Effect ( [SPELL x] section ), both SRC and the default object are the caster, one has to
			refer to SRC.ACT get the affected object.


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



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



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



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








