Updated entity scripting (markdown)

entity-scripting.md

@@ -15,7 +15,7 @@ This way you can use entities from the base game out-of-the-box, without copying
 
 # State machine
 
-Each entity is implcitly a [[state machine|https://en.wikipedia.org/wiki/Finite-state_machine]]. To summarize, an entity can have a current state (e.g. STATE_IDLE) and eventually transition to a new state (e.g. STATE_ATTACK).
+Each entity is implicitly a [[state machine|https://en.wikipedia.org/wiki/Finite-state_machine]]. To summarize, an entity can have a current state (e.g. STATE_IDLE) and eventually transition to a new state (e.g. STATE_ATTACK).
 When a state transition happens, the `enterState()` and `exitState()` interface functions are called. This is useful to script simple interactions and behaviors and model the transitions (e.g. animation changes) between states cleanly.
 
 # Interface functions
@@ -26,7 +26,7 @@ Most of them are optional; the game will try to call it and if that doesn't work
 Beware! This means that if your interface function throws an error, it will be considered non-existent and never called again for the entity that caused the error. This is probably not what you want, so have an eye on the error log and fix your code if that happens.
 If you get errors like `jellysmall : Attempt to call a nil value (???:0) animationKey` this is usually the normal clutter that appears when an interface function isn't defined.
 
-## List of interaface functions
+## List of interface functions
 
 `me` is the entity currently processed. Functions are optional unless noted otherwise.
 
@@ -57,9 +57,11 @@ When an entity's [[death scene]] is enabled, `STATE_DEATHSCENE` is entered on de
 
 ### `function exitState(me)`
 
-Called just before `enterState()`. At the time of the call, the old state is still current. There is no way to obtain the next state.
+Called just before `enterState()`. At the time of the call, the old state is still current.
+Use `entity_isState(me, STATE_WHATEVER)` or `entity_getState(me)` to check the current state.
+There is no way to obtain the next state.
 
-### `function damage(me, attacker, bone, damageType, dmg)`
+### `function damage(me, attacker, bone, damageType, dmg, hitX, hitY, shot)`
 
 Called when an entity receives damage. The game uses this function to check whether damage should be applied or not.
 If the function returns `true`, does not exist, or fails, damage is applied.
@@ -69,63 +71,99 @@ If the function returns false, damage is not applied.
 * `bone` is the bone that was hit in case the damage was caused by bone collision.
 * `damageType` is the [[type of damage|damage types]] that is about to be applied.
 * `dmg` is a positive number holding the amount of damage that will be applied.
+* `hitx, hitY` are the world coordinates where the damage was caused, if available.
+* `shot` is the shot that caused the damage, if available.
 
 ### `function msg(me, message, value)`
 
 Called when a message is received (sent via `entity_msg(me, message, value)`. This function is substantially different in OSE and previous versions:
 
-* Pre-OSE: Message is a string, value may can be a number, entity, or node. Due to how entity pointers are encoded in pre-OSE, value will always be a number, so message sender and receiver need to agree on how to interpret value, otherwise it'll crash. Communication is unidirectional only, i.e. if you want to answer, you'll have to send a message back.
+* Pre-OSE: Message is a string, value may can be a number, entity, or node. Due to how entity pointers are encoded in this version, value will always be a number, so message sender and receiver need to agree on how to interpret value, otherwise it'll crash. Communication is unidirectional only, i.e. if you want to answer, you'll have to send a message back.
 * OSE: Message handling is variadic, i.e. `msg(me, ...)` receives all parameters from the corresponding `entity_msg(me, ...) call. Values returned from `msg()` are forwarded to and returned by `entity_msg()`. This allows for easy bi-directional communication.
 
 
 ## Special interface functions
 
-* `function action(me)`
+### `function activate(me)`
 
-* `function activate(me)`
+Called when an entity is activated (default right click).
+An entity must previously be made activatable via `entity_setActivationType(me, AT_CLICK)` or `entity_setActivation(me, AT_CLICK, radius, range)`
 
-* `function animationKey(me)`
+### `function animationKey(me, key)`
 
-* `function castSong(me)`
+Called when the entity has an animating skeleton and the animation reaches a keyframe. `key` is the ID of the keyframe. Use `entity_getAnimationName(me)` to get the animation name.
 
-* `function canShotHit(me)`
+### `function canShotHit(me, attacker, bone, damageType, dmg, hitX, hitY, shot)` __[OSE only]__
 
-* `function cookFailure(me)`
+Same parameters as `damage()`.
 
-* `function deathNotify(me)`
+Called to check whether a shot should actually hit an entity. This function is only called when there is a collision, and is used to decide whether to collide or whether the shot passes through.
+If the function returns false, the shot passes through. If the function returns true, doesn't exist, or causes an error, the shot hits.
 
-* `function dieEaten(me)`
+### `function deathNotify(me, ro)`
 
-* `function dieNormal(me)`
+An entity has an internal _death notification list_ that stores RenderObjects that want to be notified when the entity is destroyed.
+For each entity in this list, `deathNotify(me, dead)` is called (`me` is the receiver of the notifiation, `dead` the thing that is getting destroyed).
 
-* `function entityDied(me)`
+Death notifications are set up via `entity_addDeathNotify(me, which) so that `me` tells `which` when `me` is destroyed.
 
-* `function exitTimer(me)`
+Note that this is a fairly low-level function. Death notification is delivered in all cases, even when an object is despawned by any means.
 
-* `function getIngredientEffectString(me)`
+### `function dieEaten(me)`
 
-* `function hitEntity(me)`
+Called when `me` dies after receiving damage of type DT_AVATAR_BITE or DT_AVATAR_PETBITE and an entity's eat type is not EAT_NONE.
 
-* `function hitSurface(me)`
+The eat type can be changed via entity_setEatType(me, [EAT_NONE|EAT_DEFAULT|EAT_FILE]).
 
-* `function lightFlare(me)`
+This is called after `enterState()` with STATE_DEAD.
 
-* `function preUpdate(me)`
+### `function dieNormal(me)`
 
-* `function shiftWorlds(me)`
+Called when `me` dies and the conditions for `dieEaten()` do not apply.
 
-* `function shotHitEntity(me)`
+### `function entityDied(me, dead)`
 
-* `function song(me)`
+Called when entity `dead` dies. This function is only called when entity `me` has previously asked to be notified by calling `esetv(me, EV_ENTITYDIED, 1)` beforehand.
 
-* `function songNote(me)`
 
-* `function songNoteDone(me)`
+### `function exitTimer(me)` __[removed in OSE]__
 
-* `function sporesDropped(me)`
+Called when an entity's timer (previously set by `entity_resetTimer(me)`) has expired.
 
-* `function targetDied(me)`
+The internal entity timer was removed in the OSE version as none of the vanilla scripts used this special timer.
 
-* `function useIngredient(me)`
+### `function hitSurface(me)`
 
-* `function useTreasure(me)`
+Called when the entity hits solid ground.
+
+### `function lightFlare(me)`
+
+Called when Naija uses the sun form light flare ability. Function will be called only when the distance between Naija and the entity is 2048 or closer.
+
+### `function shiftWorlds(me, lastWorld, newWorld)`
+
+Called when Naija uses the spirit form ability and switches between spirit and normal world. No other world types exist.
+
+### `function shotHitEntity(me, hit, shot, bone)`
+
+Called when a shot `shot` fired by `me` hits entity `hit`. If the hit entity uses skeletal collision, `bone` is the bone that was hit.
+
+### `function song(me, songID)`
+
+Called when Naija successfully sings a known song. Function will be called only when the distance between Naija and the entity is 1000 or closer.
+
+### `function songNote(me, noteID)`
+
+Called when Naija starts singing a Note. Function will be called only when the distance between Naija and the entity is 1000 or closer.
+
+### `function songNoteDone(me, noteID)`
+
+Called when Naija stops singing a Note. Function will be called only when the distance between Naija and the entity is 1000 or closer.
+
+### `function sporesDropped(me, sporeType)`
+
+Called when a shot hits solid ground and that shot is set to spawn an entity on impact. `sporeType` is 0 when that entity is called "NatureFormFlowers", and 2 otherwise.
+
+Alternatively, call `registerSporeDrop(x, y, sporeType)` to trigger this manually -- `x, y` is the position where the drop should be registered.
+
+Function will be called only when the distance between the drop point and `me` is 1024 or closer.