Created entity scripting (markdown)

entity-scripting.md

@@ -0,0 +1,131 @@
+
+Almost all entities are scripted. Entity scripts for mods are located in `_mods/modname/*.lua`.
+
+# Script load order
+
+When an entity named __chomper__ is loaded, the game first looks in
+
+    _mods/modname/scripts/chomper.lua
+
+If no such file exists, it falls back to the vanilla scripts:
+
+    scripts/entities/chomper.lua
+
+This way you can use entities from the base game out-of-the-box, without copying scripts.
+
+# 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).
+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
+
+Interface functions are called by the game to notify an entity of certain events.
+Most of them are optional; the game will try to call it and if that doesn't work, it remembers that and won't call the same function again.
+
+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
+
+`me` is the entity currently processed. Functions are optional unless noted otherwise.
+
+### `function init(me)` __[mandatory]__
+
+Called once when an entity is spawned. Usually used to set health, textures, attachments, etc.
+When a map is loaded, all scripted entities on the map have their `init()` function called.
+When an entity is spawned dynamically while the map is already going, `init()` is called the same way.
+
+### `function postInit(me)`
+
+Useful to set properties that depend on other entities being already inititalized.
+When a map is loaded, all entities' `init()` is called first, _then_ all entities' `postInit()` is called.
+
+### `function update(me, dt)` __[mandatory]__
+
+Called once every frame. `dt` holds the time (in seconds) since the last frame.
+The `update()` function does the bulk of the work that defines an entity. Movement, behavior, shot collision, etc. are all handled here.
+In order to ensure your code is framerate-independent, make sure you multiply values with `dt` as required.
+
+### `function enterState(me)`
+
+Called when the internal state machine transitions to a new state. The new state is already current when the function is called. Use `entity_isState(me, STATE_WHATEVER)` or `entity_getState(me)` to check the new state. Use `entity_getPrevState(me)` to get the previous state.
+
+The state is `STATE_DEAD` when an entity has died and is about to be despawned. Once an entity is in this state, it can't be changed anymore.
+
+When an entity's [[death scene]] is enabled, `STATE_DEATHSCENE` is entered on death, after which the entity always transitions to `STATE_DEAD`. No other state is allowed.
+
+### `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.
+
+### `function damage(me, attacker, bone, damageType, dmg)`
+
+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.
+If the function returns false, damage is not applied.
+
+* `attacker` is the entity that caused the damage, if available.
+* `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.
+
+### `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.
+* 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 animationKey(me)`
+
+* `function castSong(me)`
+
+* `function canShotHit(me)`
+
+* `function cookFailure(me)`
+
+* `function deathNotify(me)`
+
+* `function dieEaten(me)`
+
+* `function dieNormal(me)`
+
+* `function entityDied(me)`
+
+* `function exitTimer(me)`
+
+* `function getIngredientEffectString(me)`
+
+* `function hitEntity(me)`
+
+* `function hitSurface(me)`
+
+* `function lightFlare(me)`
+
+* `function preUpdate(me)`
+
+* `function shiftWorlds(me)`
+
+* `function shotHitEntity(me)`
+
+* `function song(me)`
+
+* `function songNote(me)`
+
+* `function songNoteDone(me)`
+
+* `function sporesDropped(me)`
+
+* `function targetDied(me)`
+
+* `function useIngredient(me)`
+
+* `function useTreasure(me)`