ObjectEvents

ObjectEvents

Objects in Frogatto receive events based on certain conditions, which they can handle using an event handler. Events are easily one of the single most important concepts in frogatto - they, and the FFL code inside them handle virtually all of the controls and game logic. Events typically are triggered in one of a few ways; either some game state automatically triggers them (such as two objects colliding, or an object being created), some periodic timer fires an event (such as on_process, or on_timer), or objects can explicitly fire events at themselves or another object via the fire_event() function. This page documents all the events that objects can receive and when they receive them. The vast majority of events will only be fired once their target object is active, although there are exceptions to this rule (such as `on_start_level`) - this means most events fired at a sleeping/inactive object will wait in a queue and be executed once the object is activated again. Typically, "being active" means an object needs to be on-screen, but it's also possible to set flags that make an object always active, or that make objects activate within a wide margin of the screen.

For an example of a basic event, on_create="debug('hi')" prints a 'hi' to screen when the object it is in is created. The code debug('hi'), between the double-quotes, is just an example; you can put any FFL code in there.

Events

Event name	Arguments	Triggering Condition
on_start_level	(none)	Triggered when the level starts its first cycle. Triggered for all objects in the level whether they are active or not. Not executed when loading a save. Not executed on spawned objects.
on_load	(none)	Triggered at the start of an object's first execution cycle when the object becomes active. Is triggered for a new level, for loading a level, and for spawning an object.
on_create	(none)	Triggered at the start of an object's first execution cycle when the object becomes active. Triggered for a new level, for spawning an object, but not for existing objects when loading a saved level.
on_done_create	(none)	Triggered immediately after create.
on_become_active	(none)	Triggered when an object becomes active after a period of inactivity.
on_surface_damage	(none)	Triggered when the object is standing on a tile that causes damage.
on_enter_anim	(none)	Triggered when the object enters a new animation
on_enter`_(xxx)_`anim	(none)	Triggered when the object enters the animation '`xxx`'
on_end_anim	(none)	Triggered when the object reaches the end of an animation. Only triggered if the object naturally reaches the end of an animation rather than terminating it early.
on_end`_(xxx)_`anim	(none)	Triggered when the object reaches the end of '`xxx`' animation.
on_leave_anim	(none)	Triggered when the object leaves an animation for any reason.
on_leave`_(xxx)_`anim	(none)	Triggered when the objects leaves animation '`xxx`' for any reason.
on_collide_level	(none)	Triggered when an object's non-solid area collides with part of a tile.
on_collide_head	area, collide_with, collide_with_area	Triggered when the top of an object's solid area collides with a solid part of the level or another solid object.
on_collide_feet	area, collide_with, collide_with_area	Triggered when the bottom of an object's solid area collides with a solid part of the level or another solid object.
on_collide	area, collide_with, collide_with_area	Triggered when the side of an object's solid area collides with a solid part of the level or another solid object.
on_collide_damage	surface_damage	Triggered when an object collides with a tile that does damage.
on_stuck	(none)	Triggered when an object is 'stuck' in a small pit without its feet able to touch the ground.
on_jumped_on	jumped_on_by	Triggered when an object is jumped on by another object.
on_process	(none)	One of the two most-useful events - this is triggered every "cycle" (1/50 of a second), if an object is active. Unlike the similar `on_draw` event, this will fire even if the game skips frames for performance (that is, when the game starts skipping frames, it only skips drawing - it still calculates object behavior during those skipped frames. If you have stuff that's _purely_ visual, putting it in `on_draw` would be a manual optimization hint.).
on_process`_(xxx)`	(none)	Triggered at the start of an active object's processing cycle if its current animation is '`xxx`'
on_timer	(none)	Triggered at the start of every n processing cycles for an active object. n is given by the object's timer_frequency attribute.
on_enter_water	(none)	Triggered when an active object that wasn't previously in water enters water.
on_exit_water	(none)	Triggered when an active object that was in water exists the water.
on_change_solid_dimensions_fail	collide_with	Triggered when an attempt is made to change an object's solid dimensions, but this would cause a collision.
on_add_object_fail	(none)	Triggered when an attempt is made to add an object but it can't be added due to there being no room and causing a solid collision.
on_change_animation_failure	previous_animation	Triggered when an attempt is made to change an object's animation but the new animation has different solid area and would cause a collision.
on_die	(none)	Triggered when an object's hitpoints are reduced to 0 or less, or when die() is called on the object. Not called when an object is removed using remove_object().
on_interact	(none)	Triggered when the player interacts with the object.
on_child_spawned	parent, child	Triggered when an object successfully spawns a child object. Note: this is only fired in response to spawn(), not in response to add_object() or other means of creating an object.
on_spawned	spawner, child	Triggered when an object is successfully spawned. Note: this is only fired in response to spawn(), not in response to add_object() or other means of creating an object. Unlike on_create, this has the special property of being fired immediately on the same frame as the spawn() function is called, and this will work recursively if it, in turn, spawns another child - all of them will immediately appear on the same frame. Thus, this is the event to use to set up 'trees' of related objects, such as platforms and ropes. Also unlike on_create, this offers convenient access to the parent.
on_draw	(none)	Triggered during every cycle, nominally when an object is drawn. Naively, one might expect this to be identical to `on_process`; the key difference is that this is not fired during skipped frames (which would get skipped during heavy processing), whereas on_process is always fired even for skipped frames. Another big usage of this is that unlike `on_process`, the `level.camera_position` variable is updated to be correct by the time `on_draw` is fired; if you need to keep an object's position in synch with the camera, this is the event to do it in - on_process would have a frame's worth of lag.
on_begin_dialog	(none)	Triggered whenever a dialog begins.
on_ctrl`_(xxx)`	(none)	Triggered when a control key is pressed. `xxx` = (left/right/up/down/jump/attack/tongue)
on_end_ctrl`_(xxx)`	(none)	Triggered when a control key stops being pressed.
on_mouse_(xxx)	mouse_x, mouse_y, mouse_index, mouse_button	Triggered by mouse buttons being pressed/released or mouse motion over an active object at the mouse location. mouse_x, mouse_y are the current level x and y locations. mouse_index is a number, most useful in the case of touchscreen devices where every finger touch is a different mouse. mouse_button is a the mouse button being pressed, left=1, middle=2, right=3, mouse wheel up=4, mouse wheel down=5, 6&7 are side buttons if the mouse supports them. mouse_button is not passed to the on_mouse_move event.
on_click	mouse_x, mouse_y, mouse_index, mouse_button	Click event passed to the item at the top of the z-order when items are stacked together. The order of testing is z-order, then sub-z-order, then the item with the highest midpoint value of the z-order and sub-z-order are the same for multiple items. See on_mouse_(xxx) for a discussion regarding the arguments passed to the handler.
on_mouse_(xxx)*	mouse_x, mouse_y, mouse_index, mouse_button, handled	Triggered by mouse buttons being pressed/released and mouse motion. The full set of names is on_mouse_up*, on_mouse_down*, on_mouse_move*. These events are given to *every* object on a level, though the expectation is that the number of objects actually implementing handlers would be small. The arguments to the function are interpreted in the same way as for the on_mouse_(xxx) handlers. The exception being the handled parameter which indicates that there was an active object under the mouse position that got the message first.