===============================================================================

		RISEN3D v2.2.00   SCRIPTING METHOD

===============================================================================

NOTE	This replaces the method used in v2.1.00 which is now defunct.


v220-4	Autoload, for development purposes, scp_defn, scp_zoff, sndinfo files.
	Released files should have these as embedded lumps.
	Allowing files to be loaded when developing maps makes the development
	considerably easier.

  The rules are as follows;
 
  a)    Files are only read in if the -devmap switch exists.
  b)    The files must be in a pwad udir directory together with the pwad.
  c)    File extensions, when used, are ignored.
  d)    Only the first instance of a file is loaded.  Any others are ignored.
 	As such there must only be one instance of the file by name
	(e.g. you should not have scp_defn.txt and scp_defn.bak together in
	the udir folder as there is no guarantee as to which will be loaded)
  e)    If the pwad contains SCP_DEFN, SCP_ZOFF, SNDINFO lumps then any such
	will be ignored where a file of the same name has been loaded.
	IOW a file, if it exists, will take precedence.


===============================================================================
 OVERVIEW  - The Risen3D scripting method
===============================================================================

 The Risen3D scripting method is an interactive custom model based system
 and requires a basic knowledge of the R3D (jDoom) model structure and how
 it correlates with definition files (deds).

 Scripting allows for a wider range of effects in a map.

 The scripting in general uses line triggers (use, walkover and gunfire)
 to initiate scripts.

 The method is model specific. You don't have to be able to create models
 as existing ones can be used, feel welcome to use any models contained in 
 the scripted maps available on the Risen3D website.

 A script is stored to the pwad using the name SCP_DEFN (SCP_ZOFF, SNDINFO).

 Where necessary you can script without a model by setting up a dummy model
 in a definition file.

 Although Risen3D v2.2.00 scripting is fully functional it could be extended
 further.  Any future development or tutorials will be solely dependant on the
 degree of interest shown.

 

===============================================================================
 MODELS
===============================================================================

 There are three basic groups of models Risen3D uses:

 1) The standard Risen3D model set.

 2) Custom models are models which are not activated by triggers, can be
    anything in the range of 7000-7599. They are also referred to as 
    architectural (things) models. A maximum of 200 Custom Models can be used per map.

 3) Interactive models (amodels) are custom models activated by scripted
    line triggers. They use script spots which are linked to custom models.

 The way in which Interactive models are animated is by either the death
 state or the raise state so, in effect, the way we get an interactive model
 to behave in a particular manner is to simply kill it, in other words bring
 about it's death state. Using the raise state of an interactive model would
 return it to it's original status. This principle is not hard to grasp
 because this is the way Doom handles states to achieve basic sprite
 animations, models are no more than mirrors of these states. The scripting
 method simply deploys Doom's technique of stepping through a sequence of
 states (frames).

 

===============================================================================
 SCRIPTS
===============================================================================

 The script is just a text file stored to the pwad using the named SCP_DEFN. 

 Script specific map THINGS have three categories:

 SCRIPT SPOT
	a) a THING in the range 7900 to 7999 or 6900 to 6999
	b) links to the model designated in the ded.

 LINEDEF SPOT
	a) a THING in the range 7700 to 7799 or 6700 to 6799
	b) placed on a line trigger to activate a script.

 ACTION SPOT
	a) a THING in the range 7800 to 7899 or 6800 to 6899
	b) map position of an intended spawned mobj.

 RULES;

 1) A 79nn/69nn THING can only be set once in a map.

 2) 78nn/68nn THINGs are used to spawn other THINGs.
    They are purely scripted and have no nn correspondence.
    They must also be linked to a 79nn THING even if that is not used for any
    other purpose. Where this is necessary then no SPAWNSPOT def should be used.

 3) Line actions are set using a 77nn/67nn THING or THINGs placed on lines.
    A 77nn THING must be on a line.
    77nn THINGs are linked to a 79nn THING by nn.
    No 77nn things means nothing will happen.
    More than one instance of a 77nn THING can be used.
    Map options are used with 77nn THINGs to define their action.
    No options set (i.e. easy, medium, hard, deaf, multiplayer etc.) means it
    purely links a trigger line with it's 79nn owner.

    Actions with options set;

    EASY     - will set line to blocking.

    MEDIUM   - will link that line directly to it's owner to allow the owner to be
               reset.

    HARD     - will cause that line to activate a crossing line action.

    DEAF     - used to set a script line special from the script.

    NOT DM   - used to trigger a line but only when a 79nn's amodel is logically dead

   NOT CO-OP - used to trigger a line but only when a 79nn's amodel is logically alive

   This allows mixing actions whilst using the same 77nn number.

 4) ONDEATH refers to the state of a THING spawned at SCRIPT SPOT

 5) DELAY values are in tics. 35 tics = 1 second


===============================================================================
 PRIMARY KEYWORDS
===============================================================================

 NOTE: this is subject to change and SCP_DEFN_Header.txt and SCP_ZOFF_Header.txt
       which can be found in ..\Risen3D\R3D_Docs\Editing\ should be consulted as
       these are kept up to date.

 -------

 MAP <number>
	this must be specified at the start of the script.
	A scripts terminates either at the file's end or when another
	MAP keyword is encountered.

 ------- SPAWN an AMODEL
 SPAWNSTART <SCRIPT SPOT> <AMODEL> <SPAWN: ALIVE 1, DEAD 0>

 ------- SPAWN a vertical door
 # A vertical door's base is tied to the ceiling of a rising sector.
 # The rising sector (which must also be the amodel's sector is used for
 # blocking only - it is not drawn.
 # If, when closed, the door can be viewed through or around then the sector's
 # ceiling height should be set at least 1 above the floor height to prevent
 # occlusion.

 SPAWNVDOOR	<SCRIPT SPOT> <AMODEL>
		<REQUIRED RENDERING HEIGHT OF BLOCKING SECTOR'S CEILING ABOVE FLOOR HEIGHT>
		<HEIGHT TO RISE ON DEATH> <TIME TO RISE - TICS>

 ------ Used where the model itself is a null type, therefore not rendered.
 
 SPAWNDUMMY <SCRIPT SPOT> <AMODEL>

 ------- Set z offset

 SETZ <SCRIPT SPOT> <Z HEIGHT above floor> <FALL = 1 STAY PUT = 0>

 ------- On death actions

 ONDEATH <SCRIPT SPOT> { second level SCRIPT }

 ------- Linking two things
	SPOT2 will be triggered when SPOT is triggered and must not own any 77nn things.

 COTRIGGER <SCRIPT SPOT> <SCRIPT SPOT2>

 ------- Flags

 SETTHINGFLAGS <DOOMEDNUM> <FLAGS>
	Used to set bounce, friend or touchy flags with a particular mobj
	Values are 1-Touchy  2-Bounces  3-Friend
	These canot be used with types 6700 to 7999

 ------- Allows model to drop an item when killed

 DROPITEM	<THING TYPE> <a b c d>
	Associates 4 items that can be dropped by a Thing.  The Thing must be a 6XXX
	type.  Item a to d will be selected randomly.  This allows a certain amount
	of flexibility.  E.g. If the same item must always be dropped then a to d
	would all be set to the item type.  If an item should be dropped with one
	chance in four then a would be set to the item type with b, c and d set to 0.
	If one of four different items should be dropped with equal probability then
	a to d would each be set to each item type.  And so on...

------- Allows amodel to be resurrected if line is retriggered 
 
 RESETMANUAL <SCRIPT SPOT>

 ------- Set a line sound

 SETLINE <LINEDEF SPOT> <1 = ALWAYS 0 = ONMOVE> <SOUND lumpname>

 ------ allows sight although blocked

 SEETHRULINE <LINEDEF SPOT>
		
 ------- Set sound on reset

 ONRESET <AMODEL> <SOUND lumpname>

 ------- Force hud scale

 HUDSCALE <SCALE>  // Scales pwad textures used for the hud.
 	Allowable range 10 to 40

 ------- Show text/delay on endlevel

 Endlevel will only be activated if all the listed 79nn amodels are dead.

 ENDLEVEL	<DELAY to show text> <DELAY from start of showing text to ending level>
			<MASSACRE 1 or 0> "text" {list of 79nn amodels}

	Endlevel will only be activated if all the listed 79nn amodels are dead
	and if a positive number has been used for
	<DELAY from start of showing text to ending level>.
	Using a negative number still gives the same delay as with a
	positive value but prevents the level from ending.


 ------- Second level ONDEATH SCRIPT keywords

 IFKEYS { list of key identifiers }

	If included then none of the other ONDEATH commands will be run when a
	line is triggered unless the keys in the list are held by the player
	with the exception of ONLOCKED.

	The identifiers are;
	card  keys - blue red yellow; CBx CRx CYx
	skull keys - blue red yellow; SBx SRx SYx

	where x is 0 or 1.  If x is 1, assuming a monster line trigger is used, then
	the door cannot be opened by a monster unless the player has the key card.
	Multiple identifiers should be separated by spaces e.g. { CB0 CR0 CY0 }
	In the absence of a ONLOCKED definition then the standard message noting
	key requirement where not possessed is displayed and the usual oof sound
	is played.

 REMOVEHUDKEY
	Used where a key triggers a replacement model following which it is not
	wanted to be seen in the (minimised) HUD.

	NOTE: this will only work if the Thing being replaced uses a single key

 ONLOCKED <SCRIPT SPOT> <SOUND lumpname> <"text string">
	Used, if required, with IFKEYS.

 SPAWN <ACTION SPOT> { item }
	item = <doom edit num> <z off> <delay in tics> <spawn fog 0 or 1>
	Up to 10 items can be defined

 SPAWNONCE <ACTION SPOT> { item }
	item = <doom edit num> <z off> <delay in tics> <spawn fog 0 or 1>

	Used where multiple trigger lines access the same t79nn and where after being
	triggered by the first instance all other triggers should be ignored.

 KILL <SCRIPT SPOT> <DELAY> <WAIT if occupied = 1 else 0>

 REPLACE <SCRIPT SPOT> <THING>

 TOGGLEREPLACE SCRIPT SPOT> <THING> <THING2>	
	Note: forces RESETMANUAL if not defined

 RESETMODEL <SCRIPT SPOT> <DELAY>

 SETTRIGGER <SCRIPT SPOT> <special>
	line's special, set in the map, must be 0 or 8106

 STOPSOUND <SCRIPT SPOT>

 RESURRECT <DELAY in tics>

 UNBLOCK <DELAY in tics>

 SETTAGGED <special>
	line's special set in the map must be 8107 and line must be tagged

 TEXT <SHOW: ONCE = 0, REPEAT = 1> <"text string">

 PLAYSOUND <SOUND lump name> <LOOP 0 or 1> <VOLUME 0.0 to 1.0> <ATTENUATE 0 or 1>

 KILLAMBIENT <AMBIENT THING - range 14001 to 14064> 

 REMOVE


===============================================================================
 SIMPLE EXAMPLE - door model
===============================================================================

 Here is how a simple script would be constructed.
 In a script the double slash is used to denote a comment.

-------------------------------------------------------------------------------

// The map name must be the first entry

MAP01

// Link a script spot (7905) to the DoomEd number (7010) of the actual model
// which  is declared in the ded file. The 1 at the end indicates the model
// will be spawned alive, 0 would be dead.

SPAWNSTART 7905 7010 1 

// Designate the action required when the model is activated (killed) which
// would occur if an action spot (7705) were placed on a line trigger and
// the trigger is activated.
// In this example a sound lump 'DOOR' is played when a door is opened.

ONDEATH 7905 {
	PLAYSOUND DOOR 0 1 1
}

// This could also be written ONDEATH 7905 { PLAYSOUND DOOR 0 1 1 }
// Note that only space separators are supported

-------------------------------------------------------------------------------

 The best way to grasp how the scripting method is implemented is to examine
 the Scripts.wad, Scripts.ded and the text copies of the imported scripts.

 The above mentioned are contained in the 'Script Examples' download available
 from the Risen3D website.

 Genetic Disaster can be used as a study case for more advanced scripting
 techniques.  To read a lump just put -dumplump SCP_DEFN on the global
 command line.  R3D will dump the lump to Risen3D/R3Ddump as, in this
 case, SCP_DEFN.lmp  Rename it to SCP_DEFN.txt.  It can now be read
 using a text editor (e.g. notepad.exe)

 Other script lumps names are SCP_ZOFF and SNDINFO.

 
===============================================================================
LINEDEF TRIGGERING
===============================================================================

 The triggering linedef used with THING 77xx (67xx) must have a linedef
 special set in the range; 8064 to 8079 OR 8080 to 8085.

 Linedef sector tags must be 0.

 8064 - 8066 are for standard lines.

 8080 - 8085 are for a special trigger linetype that will block everything
 until the linedef is triggered. The timeout to blocking being removed
 following triggering can be set using the secondary keyword UNBLOCK.
 Secondary keywords are used with the ONDEATH command. A value set with
 UNBLOCK is in 1/35ths of a second. So a value of 35 will block for a
 further 1 second following triggering.

 USE types
 	8064 and 8080 - player triggered only.
	8065 and 8081 - monster triggered only.
	8066 and 8082 - player or a monster triggered.

 GUN types
	8067 and 8083 - player triggered only.
	8068 and 8084 - monster triggered only.
	8069 and 8085 - player or a monster triggered.

 WALKOVER types
	8070 - player triggered only.
	8071 - monster triggered only.
	8072 - player or a monster triggered.

 NOTE: 8064 and 8080 are use once types - on activation the line special is
       cleared. This allows any MT_USE triggers that were being blocked to
       now be used. If use once is not wanted then use 8088 or 8082


 Types for use with resettable models used for switches

 USE types
	8096 - player triggered only.
	8097 and 8081 - monster triggered only.
	8098 and 8082 - player or a monster triggered.

 GUN types
	8099 and 8083 - player triggered only.
	8100 and 8084 - monster triggered only.
	8101 and 8085 - player or a monster triggered.


 NOTE: 8096 to 8101 active models are reset to their spawnstate after timing
       out. Blocking lines with these types remain unaffected.
       If a switch is on an active floor then they are inhibited.

 Release types. Used to clear hold state block with A_Look().
       The hold state applies to any sentient Thing in a sector sharing the
       backsector of a line with an 8113 or 8114 special. When activated
       then the hold state is released. Until this point the A_Look action
       is dismissed leaving the Thing in its spawned state. Affected Things
       must have the mf_solid, mf_shootable and mf_countkill flags set.

       8113  Set hold on Things in backsector
             release when player walks over the line
       8114  Set hold on Things in backsector
             release when player shoots the line



 BLOCKING LINES type 8089

 If a line is placed on 77xx (67xx) x,y coords then it will act as a blocking
 line until the model coincident with 77xx (67xx) is triggered. If a timeout
 delay is required then the UNBLOCK command should be used. A value of 35
 will confer a 1 second delay following triggering before the blocking lines
 are removed.

 Where it is required that more than one line should act as a blocking line,
 to enable a model to be blocked at different faces, then this can be done by
 adding lines in the primary blocking line's backsector (types 8080-8085) and
 setting them to special 8089.

 Note that the primary line's back sector must not be the same as its front
 sector else the line will be ignored. 8089 lines should NOT have, and do not
 require, modelswitch THINGS placed on them.

 NOTE: GUN and USE types automatically treat the activating line as a
       blocking line. This does not need setting to 8089.

 WALKOVER types do not have the line set as a blocking line for obvious
 reasons.

 SETTING ADDITIONAL BLOCKING LINES:

 Add the line and set its special to 8089. Place a second THING 77xx (67xx)
 on the line i.e. having the same number as the first used to link to the
 model. If the line's backsector is different from its frontsector and
 additional blocking lines are required in the backsector then the same rule
 applies as above.

 MODELS WITH GRILL TEXTURES

 A model may be used that can be seen through - a grill for example. In this
 case you may want lines to block movement but not sight. To achieve this
 use mf2_allowsight with the model's flags2 in the definition file.

 
 TIP: If a gun line is required that blocks permanently then use a 3D
      blocking line with type 8065 to 8067. This can also be used (by
      setting a mid tex height where no mid texture is defined) to
      selectively set a target area. So shooting at a valve for example,
      where the valve is only a small part of the overall model, can give
      the impression that the valve itself must be shot by positioning the
      blocking area over the valve. To help in positioning the active trigger
      area then set the midtexture, whilst developing the map, thus making it
      visible. Subsequently removing the texture will not affect the line's
      blocking characteristics but will now make it invisible.

 NOTE: Added v220-7:
       In Doom2 a gun trigger line is activated even if the line does not block
       the path of the bullet. Thus you may have a line with a floor below the
       bullet's trajectory which gets triggered even if passing above the floor
       height. This is probably because Doom2 does not support aiming. In a
       scripted map the behaviour is changed so that a gun trigger line will
       only be activated if the line also blocks the bullet. This allows for
       high or low trigger lines that require to be aimed at. It is still
       possible, however, to enter a line in a scripted map that gets trigg-
       ered if the bullet is not blocked. This is done by setting the line's
       front and back sectors to the same sector. The behaviour with 3D lines
       remains unaffected as these have always blocked the bullet's path with
       the following exception:

       A 3D line with a masked texture in both lower textures allows bullets
       to pass. This can be overriden (added v220-31) if a midtex height of 1
       is used with no midtexture defined. 1 is used as this is hardly useful
       for blocking so is used as a flag. The height, for blocking purposes,
       is ignored.

 NOTE: Translucency is supported with 3D lines, 260 being the MBF midtex type.
       Since 3D lines also use lower textures types 277 an 278 were added for
       this. 277 sets both the mid and low textures translucent, 278 just the
       lower texture.


GMJ July 2010. Updated February 2016
