global functions
API methods included here are globally accessible within a script.
void puts(const string &in msg)
Write a string to the console on its own line.
void tputs(const string &in msg)
Write a string to the console on its own line with an additional timestamp heading.
string script_name()
Returns the name of this script. Script names are used as a way of identifiying scripts for use when working with script triggers/enemies.
bool is_playing()
Returns false in the editor and true in game
bool is_replay()
Returns true if a replay is being watched
Use after changing persistent variables via script to update values in the script panel.
scene@ get_scene()
Return the current scene object. This scene object will be valid for the entire execution of the script.
script_base@ get_script()
Return the global script object associated with this script. For technical reasons the script must implement the “script_base” interface, otherwise this api will return null.
camera@ get_camera(uint player)
Return the camera following player ‘player’. Like the scene object this object never needs to be reloaded.
- Arguments:
- player:
The (0-indexed) player index to get the camera of.
uint num_cameras()
Returns the number of cameras/players currently active.
camera@ get_active_camera()
Get the camera that is currently being viewed.
int get_active_player()
Get the player index that is currently being viewed. Shorthand for get_active_camera.player().
entity@ controller_entity(uint player)
This is deprecated, use controller_controllable which returns the same result except cast as a controllable.
controllable@ controller_controllable(uint player)
Return the entity being controlled by player ‘player’. This object is no longer valid and should be requeried when a checkpoint is loaded.
void controller_entity(uint player, controllable@ pl)
Change the controllable controlled by player ‘player’.
void reset_camera(uint player)
Reset all camera state based on the player’s current position.
string player_name(int player)
Get the player name for the player id. Defaults to “Player ” + (player + 1) if not in networking mode or the player name is not known. Returns an empty string if the player does not exist.
entity@ entity_by_id(uint id)
Return the entity with the given id. The returned entity object is no longer valid if the entity is removed from the scene either by being destroyed, unloaded, or a checkpoint is loaded. The safest thing to do is requery the entity every frame it will be used.
This function will return null if the entity has been destroyed or is not currently loaded.
controllable@ controllable_by_id(uint id)
Convenience method for entity_by_id that tries to return a controllable.
dustman@ dustman_by_id(uint id)
Convenience method for entity_by_id that tries to return a dustman.
hitbox@ hitbox_by_id(uint id)
Convenience method for entity_by_id that tries to return a hitbox.
scripttrigger@ scripttrigger_by_id(uint id)
Convenience method for entity_by_id that tries to return a script trigger.
scriptenemy@ scriptenemy_by_id(uint id)
Convenience method for entity_by_id that tries to return a script enemy.
prop@ prop_by_id(uint id)
entity@ entity_by_index(uint index)
Return the ‘index’th entity that will be steped this frame. Should only be called from ‘step’ and ‘step_post’. See * entity_by_id() for notes on liveness of this object.
void srand(uint32 sd)
Seed the random generator.
uint32 rand()
Generate a random 30-bit number.
tileinfo@ create_tileinfo()
Create an tileinfo structure. Defaults to a square virtual tile.
tilefilth@ create_tilefilth()
Create a tilefilth structure. Defaults to no filth on any edge.
sprites@ create_sprites()
Create a sprites object that can be used to draw sprites to the screen.
prop@ create_prop()
Create a prop.
entity@ create_entity(string type_name)
Create an entity object of the given type. See Creatable Entities for a list of entity types that can be created.
textfield@ create_textfield()
Create a new textfield that can be used to draw text to the screen.
filth_ball@ create_filth_ball(int filth_type, float x, float y, float baseWidth, float baseHeight, int dir, float distance)
Create a new filth ball object.
scripttrigger@ create_scripttrigger(trigger_base@ obj)
Create a new script trigger backed by the passed trigger_base object.
scriptenemy@ create_scriptenemy(enemy_base@ obj)
Create a new script enemy backed by the passed enemy_base object.
message@ create_message()
Create an empty message object.
hitbox@ create_hitbox(controllable@ owner, float activate_time, float x, float y, float top, float bottom, float left, float right)
Create a hitbox object. Note that the entity is not automatically added to the scene. However, hitboxes do automatically remove themselves from the scene sometime after activated. Hitboxes cannot be persisted and should be added to the scene with persist set to false.
canvas@ create_canvas(bool is_hud, int layer, int sub_layer)
fog_setting@ create_fog_setting(bool with_sub_layers)
Create a fog_settings structure.
fog_setting@ create_fog_setting(entity@ trigger)
Create a fog_setting structure from a fog trigger.
void add_broadcast_receiver(string id, callback_base@ obj, string methName)
Add a callback to receive all broadcasted messages with the given id. If id is blank then this receiver will instead receive all messages.
void broadcast_message(string id, message@ msg)
Send a message to all registered broadcast receivers.
bool has_embed_value(string key)
Returns true if there is an embedded file associated with the passed key.
- To embed a file into a script use a declaration like
const string EMBED_key = “file.dat”
That will seach for the file “file.dat” in embed_src/ and then script_src/. The file data will then be available to be queried by this function, get_embed_value, and can be used as sprite data in build_sprites.
string get_embed_value(string key)
Returns the embedded file data associated with the passed key. See has_embed_value for more details on how to embed a value in a script.
bool load_embed(string key, string path)
Add/replace the embed key with the file present at “content/plugins/embeds/” + path. Use forward slashes to represent path separation.
Returns true if the path was legal and an embed was successfully loaded. If it returns false any existing embed with the same key is unmodified.
int timestamp_now()
Return the current unix timestamp.
uint32 get_time_us()
Get the current microseconds.
timedate@ localtime(int timestamp)
Convert a timestamp to a timedate structure in the local timezone.
timedate@ localtime()
Convert the current time to a timedate structure in the local timezone.
timedate@ gmtime(int timestamp)
Convert a timestamp to a timedate structure in the UTC timezone.
timedate@ gmtime()
Convert the current time to a timedate structure in the UTC timezone.
editor_api@ get_editor_api()
Get editor api object if currently in editor mode.
input_api@ get_input_api()
Get input api object if currently in editor mode.
nexus_api@ get_nexus_api()
Returns a nexus_api object if called from within a nexus. Otherwise returns null.
class scene
int get_script_fx_level()
Returns the Script FX Level video setting. This is a custom option scripts can use to enable/disable custom visuals to improve performance. Possible values are:
- 0:
Off
- 1:
Low
- 2:
Medium
- 3:
High (default)
void get_video_settings(bool &out disable_stars, bool &out disable_glass, bool &out disable_wind, bool &out disable_background, bool &out disable_midground, int &out script_fx_level, bool &out window_mode, bool &out low_res_mode)
Returns the user’s current video settings.
string map_name()
Get the current level name.
int level_type()
Get the current level type.
bool jump_enabled()
Access the global flag to disable jump. For compatibility reasons these values are inverted.
void jump_enabled(bool enabled)
bool attack_enabled()
Access the global flag to disable attack. For compatibility reasons these values are inverted.
void attack_enabled(bool enabled)
bool special_enabled()
Access the global flag to disable special. For compatibility reasons these values are inverted.
void special_enabled(bool enabled)
bool dash_enabled()
Access the global flag to disable dash. For compatibility reasons these values are inverted.
void dash_enabled(bool enabled)
float time_in_level()
Get the current time in level counter (measured in milliseconds). This is the time that is displayed to the user and has those same semantics (e.g. it does not run during startup). You can multiply this by 60/1000 and round to the nearest int to get the approximate number of frames elapsed but note for particuarly long replays accrued floating point errors may make this method eventually give innaccurate results.
void save_checkpoint(int x, int y, bool use_position)
Trigger a checkpoint to be saved. Note that the checkpoint is only saved at the start of the next frame. If use_position is false (the default due to a bug and for backwards compatibility reasons) x and y are ignored and the player’s current position is used instead.
void save_checkpoint(int x, int y)
Trigger a checkpoint to be saved. Note that the checkpoint is only saved at the start of the next frame.
void load_checkpoint()
Trigger the last checkpoint to be loaded. If no checkpoint has been set yet the level will be reloaded.
float get_checkpoint_x(int player)
Get the x coordinate for the identified player of where they should respawn on death.
float get_checkpoint_y(int player)
Get the y coordinate for the identified player of where they should respawn on death.
tileinfo@ get_tile(int x, int y)
Get the tileinfo structure for the tile at the given position on layer 19.
tileinfo@ get_tile(int x, int y, int layer)
Get the tileinfo structure for the tile at the given position and layer.
void set_tile(int x, int y, int layer, bool solid, int16 type, int16 spriteSet, int16 spriteTile, int16 palette)
Overwrite a tile in the scene. See tileinfo documentation for what each of these parameters mean.
void set_tile(int x, int y, int layer, tileinfo@ tile, bool updateEdges)
Overwrite a tile in the scene using the passed tileinfo structure.
tilefilth@ get_tile_filth(int x, int y)
Get the tilefilth structure for the tile at the given location. Filth includes all things that can be on a side of a tile, i.e. all dust types and all spike types.
uint set_tile_filth(int x, int y, uint8 top, uint8 bottom, uint8 left, uint8 right, bool affectSpikes, bool overwrite)
Set the filth for a given tile position. See tilefilth documentation for a description of how to interpret the top/bottom/left/right fields.
uint set_tile_filth(int x, int y, tilefilth@ filth)
Set the filth for a given tile position using a tilefilth object.
uint project_tile_filth(float x, float y, float baseWidth, float baseHeight, uint8 type, float direction, float distance, float spreadAngle, bool top, bool bottom, bool left, bool right, bool affectSpikes, bool overwrite)
Project filth onto surfaces using the same line of sight system that is used e.g. to clear dust with attacks. Roughly speaking, the projection will be applied to any tile edge with a center that’s within ‘distance’ pixels from the rectangle centered at (x, y) with size (baseWidth, baseHeight) in the direction of ‘direction’ +/- spreadAngle.
The top/bottom/left/right flags indicate which types of surfaces can be affected. ‘affectSpikes’ indicates if spikes should be overwritten, ‘overwrite’ indicates if only edges with no filth should be affected.
Affected tiles with have their edge type set to ‘type’. See tilefilth documentation for a description on how to interpret this value.
int default_collision_layer()
Returns the current default collision layer. Normally this will be layer 19 unless modified.
void default_collision_layer(int layer)
Sets the default collision layer. Note that this value is not persisted across checkpoints. It is up to the script to set the value appropriately after a checkpoint has been loaded.
raycast@ ray_cast_tiles(float x1, float y1, float x2, float y2)
Return information about the first tile surface hit from the ray starting at (x1, y1) going to (x2, y2).
raycast@ ray_cast_tiles(float x1, float y1, float x2, float y2, raycast@ result)
Like the other ray_cast_tiles call except reuse the raycast object result. This avoids unnecessary allocations if you’re making a lot of calls per frame.
raycast@ raycast_ray_cast_tiles_ex(float x1, float y1, float x2, float y2, uint layer)
Like the other ray_cast_tiles except provide a layer.
raycast@ ray_cast_tiles_ex(float x1, float y1, float x2, float y2, uint layer, raycast@ result)
Like the other ray_cast_tiles except provide a layer.
raycast@ ray_cast_tiles(float x1, float y1, float x2, float y2, int edges)
Return information about the first tile surface hit from the ray starting at (x1, y1) going to (x2, y2). ‘edges’ is a bitset indicating which types of edges it should look for collisions with. The 1, 2, 4, and 8 bits correspond to the top, bottom, left, and right edges respectively.
Note that the game loads in data for about a 528x528 tile square centered around the camera (multiplayer uses a 144x144 square). Querying anything outside of this loaded region will give no results.
raycast@ ray_cast_tiles(float x1, float y1, float x2, float y2, int edges, raycast@ result)
Like the other ray_cast_tiles call except reuse the raycast object result. This avoids unnecessary allocations if you’re making a lot of calls per frame.
raycast@ ray_cast_tiles_ex(float x1, float y1, float x2, float y2, int edges, uint layer)
Like the other ray_cast_tiles except provide a layer.
raycast@ ray_cast_tiles_ex(float x1, float y1, float x2, float y2, int edges, uint layer, raycast@ result)
Like the other ray_cast_tiles except provide a layer.
tilecollision@ collision_ground(float x1, float y1, float x2, float y2)
Find the collision of the horizontal line segment (x1, y1), (x2, y1) with tiles as it moves downward to y2. Only collides with ground edges.
tilecollision@ collision_roof(float x1, float y1, float x2, float y2)
Find the collision of the horizontal line segment (x1, y1), (x2, y1) with tiles as it moves upward to y2. Only collides with roof edges.
tilecollision@ collision_left(float x1, float y1, float x2, float y2)
Find the collision of the vertical line segment (x1, y1), (x1, y2) with tiles as it moves leftward to x2. Only collides with left edges.
tilecollision@ collision_right(float x1, float y1, float x2, float y2)
Find the collision of the vertical line segment (x1, y1), (x1, y2) with tiles as it moves rightward to x2. Only collides with right edges.
tilecollision@ collision_ground_ex(float x1, float y1, float x2, float y2, uint layer)
Like collision_ground except provide a layer.
tilecollision@ collision_roof_ex(float x1, float y1, float x2, float y2, uint layer)
Like collision_roof except provide a layer.
tilecollision@ collision_left_ex(float x1, float y1, float x2, float y2, uint layer)
Like collision_left except provide a layer.
tilecollision@ collision_right_ex(float x1, float y1, float x2, float y2, uint layer)
Like collision_right except provide a layer.
int get_entity_collision(float top, float bottom, float left, float right, uint type)
Get all the entity collisions of a given type in the rectangle. ‘type’ should be an element from the col_type enum at the bottom of this documentation. The return value is the number of collisions found. Use get_entity_collision_index to query the index’th result.
entity@ get_entity_collision_index(uint index)
Returns the index’th entity from the last get_…_collision call.
controllable@ get_controllable_collision_index(uint index)
Convenience method for get_entitiy_collision_index that tries to return a controllable.
dustman@ get_dustman_collision_index(uint index)
Convenience method for get_entitiy_collision_index that tries to return a dustman.
hitbox@ get_hitbox_collision_index(uint index)
Convenience method for get_entitiy_collision_index that tries to return a hitbox.
scripttrigger@ get_scripttrigger_collision_index(uint index)
Convenience method for get_entitiy_collision_index that tries to return a script trigger.
scriptenemy@ get_scriptenemy_collision_index(uint index)
Convenience method for get_entitiy_collision_index that tries to return a script enemy.
int get_prop_collision(float top, float bottom, float left, float right)
Get all the prop collisions within the query rectangle. The return value is the number of prop collisions detected. Use get_prop_collision_index to query the index’th result.
prop@ get_prop_collision_index(uint index)
Returns the index’th prop from the last get_…_collision call.
void override_stream_sizes(int load_size, int step_size)
Override the default stream sizes. Stream sizes are measured in segments (16x16 tile squares). The streaming area is a square region of segments with side length given by the stream size.
- Constraints:
8 <= step_size <= load_size <= 256
- Arguments:
- load_size:
Controls when entities are loaded into memory and written back to persist.
- step_size:
Controls when an entitie’s logic will be executed.
int combo_break_count()
Returns the number of combo breaks that have been recorded for the current replay. This translates to finess scores as 0=S, 1=A, 2-3=B, 4-5=C, 6+=D
void combo_break_count(int combo_break_count)
Set the current combo break count.
void add_prop(prop@ prop)
Add a prop into the scene to be rendered each frame.
void remove_prop(prop@ prop)
Remove a prop from the scene.
void add_entity(entity@ entity)
Add an entity to the scene to be step’ed and drawn.
void add_entity(entity@ entity, bool persist)
Add an entity to the scene to be step’ed and drawn. ‘persist’ indicates if the entity should be saved and loaded using the checkpoint system.
void remove_entity(entity@ entity)
Remove an entity from the scene.
bool layer_visible(uint layer)
Access the visibility of each layer. Note that this just returns sub-layer 0 if the layer has different sublayer values.
void layer_visible(uint layer, bool visible)
Sets the visibility of all sub layers for this layer.
bool sub_layer_visible(uint layer, uint sub_layer)
Access the visibility of each sub layer. Note that hiding sub layer 10 also prevents sublayers 11-15 from rendering, so changing it is not recommended for the moment as the behaviour may change in the future.
void sub_layer_visible(uint layer, uint sub_layer, bool visible)
float layer_scale(uint layer)
Access the scaling factor of the layer. 1.0 is the standard foreground scale with lower values being used for the background. Note that this just returns sub-layer 0 if the layer has different sublayer values.
void layer_scale(uint layer, float scale)
Sets the scale of all sub layers for this layer.
void layer_scale_reset(uint layer)
Resets the scale for all sub layer on the given to its default value.
float sub_layer_scale(uint layer, uint sub_layer)
Access the scaling factor of the sub layer.
void sub_layer_scale(uint layer, uint sub_layer, float scale)
void sub_layer_scale_reset(uint layer, uint sub_layer)
Resets the scale for the given sub layer to its default value.
void reset_layer_order()
Reset the render order of the layers to the default.
void swap_layer_order(uint layer1, uint layer2)
Swap the rendering order of two layers. Note that this only changes the order that draw commands are applied and does not affect other layer attributes like fog colour or scale.
Note that layer order is not persisted across checkpoints. It is up to the script to set the layer ordering appropriately after a checkpoint is loaded.
uint get_layer_position(uint layer)
Get the render position of a layer. Normally this is just the layer index itself unless swap_layer_order has been used.
void draw_rectangle_world(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, float rotation, uint colour)
Draw a rectangle in the world scene’s coordinates. colour is an ARGB value in big endian byte order (alpha is the high byte).
void draw_glass_world(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, float rotation, uint colour)
Like draw rectangle except a blur shader is used.
void draw_gradient_world(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, uint c00, uint c10, uint c11, uint c01)
Draws a gradient to the screen like how the background is drawn.
void draw_line(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, float width, uint colour)
Deprecated, use draw_line_world instead.
void draw_line_world(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, float width, uint colour)
Draws a line between the two points.
void draw_quad_world(uint layer, uint sub_layer, bool is_glass, float x1, float y1, float x2, float y2, float x3, float y3, float x4, float y4, uint c1, uint c2, uint c3, uint c4)
Generic call to draw an arbitrary quadralateral. Specify points in counter clockwise order. Glass is not actually supported and so is_glass is currently ignored.
The engine draws quads under the hood by drawing two triangles between points (1, 2, 3) and points (1, 3, 4). Note that this means that the color at points 1 and 3 bleed into both halfs while the colors at points 2 and 4 are restricted to just one half.
void draw_rectangle_hud(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, float rotation, uint colour)
Analagous draw routines for the hud coordinate space. To scripts the hud is a 1600 by 900 pixel rectangle centered at the origin.
void draw_glass_hud(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, float rotation, uint colour)
void draw_gradient_hud(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, uint c00, uint c10, uint c11, uint c01)
void draw_line_hud(uint layer, uint sub_layer, float x1, float y1, float x2, float y2, float width, uint colour)
void draw_quad_hud(uint layer, uint sub_layer, bool is_glass, float x1, float y1, float x2, float y2, float x3, float y3, float x4, float y4, uint c1, uint c2, uint c3, uint c4)
Generic call to draw an arbitrary quadralateral. Specify points in counter clockwise order. is_glass is not supported and is ignored.
The engine draws quads under the hood by drawing two triangles between points (1, 2, 3) and points (1, 3, 4). Note that this means that the color at points 1 and 3 bleed into both halfs while the colors at points 2 and 4 are restricted to just one half.
void disable_score_overlay(bool disable_overlay)
Prevent the normal score overlay (including the combo, combo-meter, and time displays) from rendering.
audio@ play_sound(string name, float x, float y, float volume, bool loop, bool positional)
See https://gist.github.com/msg555/46f46b8b943ee93393a0a192c7703c57 for a list of sound and stream names to use.
audio@ play_stream(string name, uint soundGroup, float x, float y, bool loop, float volume)
‘soundGroup’ determines which global volume slider to apply to this sound. 1 for music, 2 for ambience, and anything else is considered a sound effect.
audio@ play_script_stream(string name, uint soundGroup, float x, float y, bool loop, float volume)
Play a stream that was loaded in using the script.build_sounds() callback.
audio@ play_persistent_stream(string name, uint sound_group, bool loop, float volume, bool script_sound)
Play a sound that will continue to play after a reset, similar to in game music. If the specified audio is already playing nothing will happen. script_sound indicates if the sound to be played is a script, or built in sound. Note that calling audio.stop() on the returned audio won’t automatically remove it from the script music registry, use scene.stop_persistent_stream instead.
bool stop_persistent_stream(string name)
Returns true if the specified persistent stream was stopped.
audio@ get_persistent_stream(string name)
Returns the specified persitent sound if it is playing, or null otherwise.
void override_sound(string sound, string override_sound, bool script_sound)
Overrides the built in sound named “sound” with “override_sound”. Any time the game tries to play that sound, the override will be played instead. script_sound indicates whether an embedded, or built in sound will be used for the override
bool has_sound_override(string sound)
Returns true if the sound has been overridden
string get_sound_override(string sound)
Returns the override for the specified sound, or an empty string
bool is_sound_override_script(string sound)
Returns true if the specified override uses a script sound
void clear_sound_override(string sound)
Clears the specified sound overrides if there is one
void clear_sound_overrides()
Clears all sound overrides
collision@ add_collision(entity@ e, float top, float bottom, float left, float right, uint32 collision_type)
Insert a new collision object into the scene.
float mouse_x_hud(int player, bool scale)
Returns the x coordinate of the mouse in the hud coordinate space. If scale is set to true will auto scale the coordinates to simulate a 1600-900 screen size. Will range between -width/2 and width/2.
float mouse_x_hud(int player)
Equivalent to mouse_x_hud(player, true)
float mouse_y_hud(int player, bool scale)
Returns the y coordinate of the mouse in the hud coordinate space. If scale is set to true will auto scale the coordinates to simulate a 1600-900 screen size. Will range between -height/2 and height/2.
float mouse_y_hud(int player)
Equivalent to mouse_y_hud(player, true)
float mouse_x_world(int player, int layer)
Returns the x coordinate of the mouse for the given player’s camera in the given layer.
float mouse_y_world(int player, int layer)
Returns the y coordinate of the mouse for the given player’s camera in the given layer.
void mouse_world(int player, int layer, int sub_layer, float &out x, float &out y)
Returns the coordinates of the mouse for the given player’s camera in the given layer and sublayer.
float hud_screen_width(bool scale)
Return the current HUD screen width in pixels. If scale is true this always returns 1600.
float hud_screen_height(bool scale)
Return the current HUD screen height in pixels. If scale is true this always returns 900.
int mouse_state(int player)
Returns the mouse state for the given player as a bitmask. See the below table for what button each bit corresponds to.
- Arguments:
- player:
the player to get input for
- Bitmask:
- 1:
wheel up
- 2:
wheel down
- 4:
left click
- 8:
right click
- 16:
middle click
void end_level(float x, float y)
Trigger the level to be ended. Note that the replay won’t actually end until the next frame if the frame has already begun. (x, y) are the respawn location if the player dies.
int plugin_score()
Access the plugin score used to add an extra criteria for ranks on leaderboards (only) when plugins are used. Lower scores rank better. The Score leaderboard is ranked by (completion, plugin_score, finesse, time) while the Time leaderboard is ranked by (plugin_score, time, completion + finesse).
The score is restricted to the rank [0, 1000].
Note that this field does nothing when the player isn’t using a plugin.
void plugin_score(int plugin_score)
entity@ add_effect(string sprite_set, string sprite_name, float x, float y, float rotation, float scale_x, float scale_y, float frame_rate)
Create a new effect based off a sprite animation.
entity@ add_follow_effect(string sprite_set, string sprite_name, float x, float y, float rotation, float scale_x, float scale_y, float frame_rate, entity@ follow, bool follow_x, bool follow_y)
Create a new effect based off a sprite animation that follows an entity.
follow_x indicates that the effect x coordinate should be computed as follow.x + x. follow_y means similar for y coordinates. If follow_x and follow_y are both false then this behaves the same as add_effect.
void get_filth_level(int &out filth, int &out filth_block, int &out enemy)
Writes the total initial amount of filth, dustblocks, and enemy life in the level to the passed variables.
void get_filth_remaining(int &out filth, int &out filth_block, int &out enemy)
Writes the current amount of filth, dustblocks, and enemy life in the level to the passed variables.
float time_warp()
The time warp field can be used to dilate time. e.g. a time_warp of 0.5 will make the world scene run in half time.
void time_warp(float time_warp)
int user_id()
Returns the user ID currently logged into the client. If the user has not logged in successfully this will return 0. If the user has logged in as guest this will return 19998. Otherwise this will be the user’s account ID as can be seen on dustkid.
int player_user_id(uint player)
Like scene:user_id except returns the user ID attached to a specific player. This is relevant during gameplay where each player may be controlled by a different client logged in with a different ID.
string replay_username()
This returns the username field attached to the replay. This is the same as the text displayed when watching a replay. If no replay is active this will return an empty string.
void clear_ghosts()
Clear any ghosts currently loaded. This is meant only to help hide replays during special events.
int get_emitter_type_id(string name)
Returns the emitter type id for the given name, or -1 if it does not exist.
void add_particle_burst(uint id, float x, float y, float w, float h, uint layer, uint sub_layer)
Create a particle burst. If the emitter type is not a burst emitter this does nothing.
uint get_emitter_type_count()
Returns the number of defined emitter types.
uint get_particle_type_count()
Returns the number of defined particle types.
emitter_type@ get_emitter_type(uint index)
Returns the emitter type with the given index, or null if the index is out of range.
particle_type@ get_particle_type(uint index)
Returns the particle type with the given index, or null if the index is out of range.
class rectangle
float top()
void top(float _top)
float bottom()
void bottom(float _bottom)
float left()
void left(float _left)
float right()
void right(float _right)
float get_width()
float get_height()
class raycast
Represents a ray cast result.
bool hit()
Returns true if the ray cast hit a tile.
int tile_x()
Returns the (tile) coordinates of the hit tile.
int tile_y()
float hit_x()
Returns the coordinates pixel coordinates where the ray actually intersects the tile face.
float hit_y()
int tile_side()
Returns 0-3 indicating the side of the edge hit from top, bottom, left, right in that order.
int angle()
Returns the angle of hit tile surface.
class tilecollision
void reset()
bool hit()
void hit(bool is_solid)
float hit_x()
void hit_x(float outside_x)
float hit_y()
void hit_y(float outside_y)
float angle()
int type()
void type(int type)
class tileinfo
Represents what tile shape and sprite is present at a tile and which edges have collisions. Does not include filth information.
uint8 type()
See the notes in the TileShape class at https://github.com/msg555/dustmaker/blob/master/dustmaker/Tile.py for how the type parameter maps to the shape of the tile.
See C’s diagram for an illustration of the different tile types. https://github.com/cmann1/PropUtils/blob/master/files/tiles_reference/TileShapes.jpg
void type(int _type)
bool solid()
Indicates whether a tile is present. The rest of the fields are irrelevant if solid is set to false.
void solid(bool _solid)
int32 angle()
Angle is a function of the type ‘type’. It indicates the angle that the non-flat edge is oriented. A square tile (type 0) has an angle of 0.
uint8 sprite_set()
See C’s reference on the different available sprite set/tile/palettes available.
https://github.com/cmann1/PropUtils/blob/master/tile-data.json https://github.com/cmann1/PropUtils/tree/master/files/tiles_reference
void sprite_set(int _sprite_set)
uint8 sprite_tile()
void sprite_tile(uint8 _sprite_tile)
uint8 sprite_palette()
void sprite_palette(uint8 _sprite_palette)
uint8 edge_top()
Each tile edge is represented by four bits. These are their meanings from least significant bit to most significant bit.
- 1 bit:
indicates edge “priority”?
- 2 bit:
whether to draw an edge cap on the left/top.
- 4 bit:
whether to draw an edge cap on the right/bottom.
- 8 bit:
indicates whether the edge has collision and can have filth.
void edge_top(uint8 _edge_top)
uint8 edge_bottom()
void edge_bottom(uint8 _edge_bottom)
uint8 edge_left()
void edge_left(uint8 _edge_left)
uint8 edge_right()
void edge_right(uint8 _edge_right)
bool is_dustblock()
Returns true if the tile is a dustblock tile.
void set_dustblock(int _sprite_set)
Set the tile’s sprite_tile and sprite_palette parameters to be the dustblock tile type in the given sprite set.
class tilefilth
Describes the filth or spikes on a tile.
uint8 top()
Each tile filth value indicates if and what type of filth or spikes are present on a given face of a tile. These values should be:
- 0:
no filth/spikes
- 1-5:
dust, leaves, trash, slime, virtual filth
- 9-13:
mansion spikes, forest spikes, cones, wires, virtual spikes
void top(uint8 _top)
uint8 bottom()
void bottom(uint8 _bottom)
uint8 left()
void left(uint8 _left)
uint8 right()
void right(uint8 _right)
class camera
int get_type()
Get the camera type. See the camera_types enum.
string camera_type()
Deprecated - use camera::get_type instead.
bool script_camera()
A flag to disable the normal camera behavior. Set this to true if you wish to manage the camera position and zoom entirely within the script.
void script_camera(bool script_camera)
entity@ puppet()
The entity the camera is following.
int player()
Get the player index for this camera.
int controller_mode()
The controller mode controls how raw game inputs are converted into intents. ispressed, posedge, negedge each convert the corresponding intent to match the corresponding key’s state: whether it’s currently pressed, was just pushed, or just released. fall_intent is always 0 with a non-standard controller_mode because there is no corresponding key bind.
Advanced mode provides standard buffering behaviour while also giving access to the down/pressed state of each input through the camera::input_* methods.
void controller_mode(int controller_mode)
void input_x(int &out left, int &out right)
Get the raw left and right input states. The down and press states are stored in the 1 and 2 bits respectively. Always returns 0 if controller mode is not set to advanced.
int input_x()
Get the raw x input state. The left and right states are store in the 1 and 2 bit respectively. Always returns 0 if controller mode is not set to advanced.
void input_y(int &out up, int &out down)
Same as camera::input_x.
int input_y()
Same as camera::input_x but for the up and down state.
int input_dash()
Same as the left or right value of camera::input_x.
int input_jump()
int input_light()
int input_heavy()
int input_taunt()
void input_double_tap(bool &out left, bool &out right, bool &out up, bool &out down)
Returns true on the frame of the double tap for each direction input.
float x()
Camera center coordinates.
void x(float x)
float y()
void y(float y)
float prev_x()
The prev x/y values are used to interpolate the camera position. If you don’t want the camera to move between the new and old camera positions reset these values appropriately. This is not necessary if you use camera.reset().
void prev_x(float prev_x)
float prev_y()
void prev_y(float prev_y)
float zoom()
Deprecated, use screen height instead.
void zoom(float zoom)
float screen_height()
Access the height of the camera in pixels.
void screen_height(float screen_height)
float screen_width()
Access the width of the camera in pixels.
void screen_width(float screen_width)
void set_lookahead(float x, float y)
Controls how far ahead the camera looks as a multiplier of the puppet velocity. Defaults to (1, 1) This value is persisted with checkpoints.
void get_lookahead(float &out x, float &out y)
void set_path_lookahead(float x, float y)
Controls how far ahead the camera looks based on the puppet velocity when attached to a camera path. Higher values result in less of an effect. Defaults to (5, 10) This value is persisted with checkpoints.
void get_path_lookahead(float &out x, float &out y)
void break_distance(float distance)
Controls how far outside of the screen the player must be to break camera as a multiplier of the screen size. Set to 1 for normal behaviour and 0 to disable. This value is persisted with checkpoints.
float break_distance()
void speed_change(float speed_change)
The rate at which the camera eases from it’s current to the target position every frame. This value is persisted with checkpoints.
float speed_change()
void set_custom_speed(float x, float y)
A custom speed added to the camera puppet speed when calculating the look ahead position. This value is persisted with checkpoints.
void get_custom_speed(float &out x, float &out y)
void set_position_override(float x, float y)
If set the camera will target this position instead of the puppet position. This value is persisted with checkpoints.
void get_target_override(float &out x, float &out y)
void clear_position_override()
Disables the override position, making the camera target the puppet again.
bool has_position_override()
Returns true if an override position is set.
void force_disconnect()
Forcibly disconnect the camera from the current path.
bool try_connect(camera_node@ node)
Attempts to connect to the given camera node. Returns true on success.
camera_node@ current_node()
The current node on the camera path.
camera_node@ next_node()
The next node on the camera path.
float editor_zoom()
Access editor zoom setting.
void editor_zoom(float editor_zoom)
void get_layer_draw_rect(float sub_frame, int layer, float &out left, float &out top, float &out width, float &out height)
Get the size of the world layer in the current frame at a given sub_frame position. This accounts for camera animations and should match the sizes used by the game.
void get_layer_draw_rect(float sub_frame, int layer, int sub_layer, float &out left, float &out top, float &out width, float &out height)
Get the size of the world layer and sub layer.
float rotation()
The camera rotation in degrees.
void rotation(float rotation)
float rotation_prev()
void rotation_prev(float rotation_prev)
float scale_x()
These do the same thing as zoom but allow you to manipulate each axis individually. Negative values are support for axis flips.
void scale_x(float scale_x)
float scale_y()
void scale_y(float scale_y)
float prev_scale_x()
void prev_scale_x(float prev_scale_x)
float prev_scale_y()
void prev_scale_y(float prev_scale_y)
void add_screen_shake(float x, float y, float dir, float force)
Add a screen shake. Only works if script_camera is false, otherwise you need to simulate your own screen shake.
fog_setting@ get_fog()
Get the current camera fog colours.
void change_fog(fog_setting@ fog, float fog_time)
Change the fog colour. fog_time controls how long the transition time from the current fog colour to this updated colour should take measured in seconds.
void change_fog(entity@ trigger, float fog_time)
Change the fog colour directly from a fog trigger. If fog_time < 0 the trigger time will be used.
void change_music(string track_name, float volume, float speed)
Change the music. name must be a valid music track name. speed controls the transition time measured in seconds.
void change_music(entity@ trigger, float speed)
Change the music directly from a music trigger. If speed < 0 the trigger time will be used.
void change_ambience(string track_name, float volume, float speed)
Change the ambience to a single track. All other track volumes will be set to 0. name must be a valid ambience track name. speed controls the transition time measured in seconds.
void change_ambience(entity@ trigger, float speed)
Change the ambience directly from a music trigger. If speed < 0 the trigger time will be used.
class camera_node
Inherits: entity
int width()
The size of this node’s area.
void width(int width)
int screen_height()
The screen height for this node.
void screen_height(int height)
int type()
This camera node’s type. See enum node_types for a list of possible values.
void type(int type)
uint connected_node_id(uint index)
Gets the id of the camera node connected to this one at the given edge index.
void connected_node_id(uint index, uint node_id)
int interest_width(uint index)
Gets the interest width for the given edge index.
void interest_width(uint index, int width)
void get_edge(uint index, uint &out node_id, int &out intereset_width)
Gets the connected node id and interest width for the given edge index.
void set_edge(uint index, uint node_id, int intereset_width)
void get_control(uint index, float &out length, float &out angle)
Gets length and angle (in degrees) of the control/tolerance handle.
void set_control(uint index, float length, float angle)
bool connect_node(uint node_id, bool update_control)
Adds a connection to node_id. This may reorder the list of connected nodes. If update_control is false control handle angles will not be recalculated. Returns true if a new connection was added.
bool connect_node(uint node_id)
bool disconnect_node(uint node_id, bool update_control)
Removes node_id from the list of connected nodes. This may reorder the list of connected nodes. If update_control is false control handle angles will not be recalculated. Returns true if a connection was removed.
bool disconnect_node(uint node_id)
bool disconnect_from_node(uint node_id)
Removes this node from a neighbouring node’s connection list. Returns true if a connection was removed.
void disconnect_all(bool update_control)
Removes all connections to and from this node. If update_control is false control handle angles will not be recalculated for neighbouring nodes.
void disconnect_all()
void remove_edge(int index, bool update_control)
Removes the connected edge at index. If update_control is set this will also recalculate control handle angles.
void remove_edge(int index)
void reorder_edges(bool update_control)
Reorders the list of connected nodes based on their relative angle.
void update_control()
Recalculate all control handle angles.
int num_edges()
The number of connections this node has.
int num_controls()
The number of control handles this node has. This should be 0 when not connected to any nodes, 2 for a node with a single connection, or match num_edges for a node with 2 or more connections.
class collision
Represents a collision hitbox used throughout the game engine. Collisions are made up of a collision type, a hitbox, and an entity. Collisions are used (e.g. when you attack an area) by querying all collision hitboxes of a certain type that intersect with a query rectangle (see scene.get_entity_collision) and returning the entities associated with each intersecting collision.
Most enemies have two collisions associated with them. The base collision is used to detect tile collisions and when the entity is clicked in the editor. The hit collision is used to detect when an enemy is attacked.
void rectangle(float top, float bottom, float left, float right)
Access the hitbox of the collision.
void rectangle(rectangle@ rect, float x_offset, float y_offset)
rectangle@ rectangle()
uint32 collision_type()
Access the collision type of this collision. See col_type for predefined types. New values may be used for custom purposes as well.
void collision_type(uint32 collision_type)
void remove()
Remove the collision from the scene. This collision will no longer be picked up by calls to get_entity_collision.
void entity(entity@ e)
Access the entity associated with this collision.
entity@ entity()
class audio
void stop()
bool is_playing()
float volume()
void volume(float volume)
float time_scale()
void time_scale(float time_scale)
void set_position(float x, float y)
bool positional()
void positional(bool positional)
class entity
void reset()
Reset the entity state to its defaults.
bool is_same(entity@ obj)
Returns true if the underlying entity objects point to the same object. This is to help deal with the issue of different entity handles pointing to the same entity object in the scene.
bool is_same(controllable@ obj)
bool is_same(dustman@ obj)
message@ metadata()
sprites@ get_sprites()
Returns the entities’ sprite object.
void set_sprites(sprites@ obj)
string type_name()
Returns the type name of the entity. This is the same string that can be passed to create_entity to make an object of the same type.
varstruct@ vars()
entity@ as_entity()
Recast this object as an entity. Unfortunately with the way the API types are setup a controllable object cannot be casted to an entity using the normal cast<T>() operator.
hittable@ as_hittable()
Attempt to recast this object as a hittable. Returns null if the entity is not a hittable.
controllable@ as_controllable()
Attempt to recast this object as a controllable. Returns null if the entity is not a controllable.
dustman@ as_dustman()
Attempt to recast this object as a dustman object. Returns null if the entity is not a dustman object.
ai_controller@ as_ai_controller()
Attempt to recast this object as an AI controller object. Returns null if the entity is not an AI controller object.
hitbox@ as_hitbox()
Attempt to recast this object as a hitbox object. Returns null if the entity is not a hitbox object.
effect@ as_effect()
Attempt to recast this object as an effect object. Returns null if the entity is not a effect object.
filth_ball@ as_filth_ball()
Attempt to recast this object as a filth ball object. Returns null if the entity is not a filth object.
scripttrigger@ as_scripttrigger()
Attempt to recast this object as a scripttrigger object. Returns null if the entity is not a scripttrigger object.
scriptenemy@ as_scriptenemy()
Attempt to recast this object as a scriptenemy object. Returns null if the entity is not a scriptenemy object.
camera_node@ as_camera_node()
Attempt to recast this object as a scriptenemy object. Returns null if the entity is not a scriptenemy object.
uint id()
Return the ID associated with this entity that can be used with the entity_by_id() function. Non-persistant entities (i.e. the player entities) will have an id of 0 and cannot be found with entity_by_id().
bool destroyed()
Has this entity been removed from the scene.
float x()
The position of the entity. For most entities the position is the bottom center of their collision rectangle. These functions will automatically adjust the base and hit collisions associated with this entity.
void x(float x)
float y()
void y(float y)
void set_xy(float x, float y)
void centre(float &out x, float &out y)
A shortcut method to calculate the centre of this entity’s hitbox, which for some entities may not be the same as its origin/position.
float centre_x()
float centre_y()
void set_centre(float x, float y)
Sets this entity’s position so that the centre of its hitbox will be positioned at x, y
float rotation()
The rotation of the entity in degrees. This should be in the interval [-180, 180].
void rotation(float rot)
int layer()
The layer that the entity should be drawn in.
void layer(int layer)
int face()
The direction the entity is facing. Should be -1 for left or 1 for right. If this is a controllable entity and the attack state is not attack_type_idle (i.e. non-zero) then the controllable will temporarily be facing the direction given by attack_face() instead.
void face(int face)
int palette()
The palette of sprites to use. Typically this should just be set to 1 as most entities don’t have alternative palettes for their animations.
void palette(int palette)
float time_warp()
Changes the perceived game speed for the entity.
void time_warp(float time_warp)
collision@ base_collision()
Returns the collision rectangle used to select the entity in the editor.
rectangle@ base_rectangle()
void base_rectangle(float top, float bottom, float left, float right)
void base_rectangle(rectangle@ rect)
void send_message(string id, message@ msg)
Send a message to the entity. Currently, scripttrigger and scriptenemy entities are the only entities that can do anything with the message.
string sprite_index()
The sprite name currently being rendered for this entity.
void sprite_index(string spr_index)
class hittable
Inherits: entity
float x_speed()
Returns the x/y component of the velocity measured in pixels per second.
float y_speed()
void set_speed_xy(float x_speed, float y_speed)
Sets the velocity using x/y components.
rectangle@ hurt_rect()
Returns a copy of the hurtbox rectangle for the entity.
float scale()
Access the scale of the entity. A scale of 2.0 means double the usual size. A scale of 0.5 means half the usual size. If ‘animate’ is true the scale changes will gradually take affect.
void scale(float scale)
void scale(float scale, bool animate)
int life_initial()
Gives the initial life associated with this entity. This also usually corresponds to how much dust the enemy contributes toward completion score calculations.
int life()
Access the number of hits remaining on this enemy. Setting the life negative will not destroy the enemy until it is hit again. A few controllables don’t make use of this field (e.g. hittable_apple).
void life(int life)
hitbox@ hitbox()
Returns the current hitbox controller for this entity. This may be null if the controllabe isn’t attacking. The hitbox object associated with each controllable is recreated with each attack.
collision@ hit_collision()
Returns the hurt collision object for this controlable.
rectangle@ hit_rectangle()
void hit_rectangle(float top, float bottom, float left, float right)
void hit_rectangle(rectangle@ rect)
int team()
Access the team of the hittable. See the team_types enum for predefined values. Normally entities will only hit/target entities of the opposite team.
void team(int team)
float freeze_frame_timer()
Access the freeze frame timer for this entity. This timer usually runs at 24 units/s.
void freeze_frame_timer(float freeze_frame_timer)
void on_hit_callback(callback_base@ base_obj, string callback_method, int arg)
Set a callback when the entity is hit. The callback should have the signature “void func_name(controllable@ attacker, controllable@ attacked, hitbox@ attack_hitbox, int arg)”. hittable@ is allowed as the attacker/attacked may not be controllables e.g. in the case of quills. The ‘arg’ value passed to on_hit_callback will match the ‘arg’ parameter passed to the callback.
void on_hurt_callback(callback_base@ base_obj, string callback_method, int arg)
Set a callback when the entity is hurt. The callback should have the signature “void func_name(controllable@ attacked, controllable@ attacker, hitbox@ attack_hitbox, int arg)”. hittable@ is allowed as the attacker/attacked may not be controllables e.g. in the case of quills. The ‘arg’ value passed to on_hurt_callback will match the ‘arg’ parameter passed to the callback.
class controllable
Inherits: hittable
float prev_x()
The prev x/y values are used to interpolate the entity position.
void prev_x(float prev_x)
float prev_y()
void prev_y(float prev_y)
void set_speed_xy(float x_speed, float y_speed)
Sets the velocity using x/y components.
float speed()
Returns magnitude of the velocity.
float direction()
Returns the direction of the velocity vector. Right is 90, Left is -90, Up is 0, Down is -180 or 180.
void set_speed_direction(float speed, int direction)
Sets the velocity using polar components.
rectangle@ collision_rect()
Returns a copy of the collision rectangle for the entity.
int state()
Returns the current state of the entity. See the ‘state_types’ enum at the end of this documentation for details on the different states names. The majorify of the states are only used by dustman.
void state(int state)
string attack_sprite_index()
The sprite name currently being rendered for this entity.
void attack_sprite_index(string attack_spr_index)
float state_timer()
The state timer for this entity. This tracks where the entity is in the state animation.
void state_timer(float state_timer)
float stun_timer()
The stun timer for this entity. This counts down to 0 which ends the stun animation.
void stun_timer(float stun_timer)
int attack_state()
The attack state for this entity. See ‘attack_types’ at the bottom of this documentation for the attack state types.
void attack_state(int attack_state)
float attack_timer()
The timer that keeps track of how long the attack has been active.
void attack_timer(float attack_timer)
int attack_face()
The direction the controllable is facing while attack state is not attack_type_idle.
void attack_face(int attack_face)
int x_intent()
Indicates what direction the entity wants to move in the x direction. -1 for left, 0 for neutral, 1 for right.
void x_intent(int x_intent)
int y_intent()
Indicates what direction the entity wants to move in the y direction. -1 for up, 0 for neutral, 1 for down.
void y_intent(int y_intent)
int taunt_intent()
0 indicates taunt not pressed. 1 indicates taunt is pressed. 2 indicates taunt is pressed and the intent has been used.
void taunt_intent(int taunt_intent)
int heavy_intent()
0 indicates no heavy intended. 10 indicates heavy pressed. When heavy is released and the intent was never used it counts down from 10 to 0 until the intent ends up being used or it hits 0. 11 indicates heavy is pressed and the intent has been used.
void heavy_intent(int heavy_intent)
int light_intent()
Functions the same as heavy_intent()
void light_intent(int light_intent)
int dash_intent()
0 indicates no dash key press. 1 indicates the dash key pushed this frame. 2 indicates the dash key pushed this frame and the intent has been used.
void dash_intent(int dash_intent)
int jump_intent()
Same as taunt_intent()
void jump_intent(int jump_intent)
int fall_intent()
Same as dash_intent()
void fall_intent(int fall_intent)
bool ground()
Returns true if the controllable is in contact with the corresponding surface type.
void ground(bool ground)
bool roof()
void roof(bool roof)
bool wall_left()
void wall_left(bool wall_left)
bool wall_right()
void wall_right(bool wall_right)
int ground_surface_angle()
If the corresponding surface flag is set then these fields contain the angle of the surface the entity is touching.
int roof_surface_angle()
int left_surface_angle()
int right_surface_angle()
float run_max()
void run_max(float run_max)
float run_start()
void run_start(float run_start)
float run_accel()
void run_accel(float run_accel)
float idle_fric()
void idle_fric(float idle_fric)
float skid_fric()
void skid_fric(float skid_fric)
float fric()
Get/set the friction value used by some enemies to control air, turn, or attack friction.
void fric(float fric)
void set_ground_angles(int slope_min, int slope_max, int slant_min, int slant_max)
Change which ground surface angles this entity considers slopes, or slants. Slopes default to 45, and slants to 26. Required to allow non-45 degress slope sliding and for the player sprite to automatically rotate to match the ground angle.
void set_roof_angles(int slope_min, int slope_max, int slant_min, int slant_max)
Change which roof surface angles this entity considers slopes, or slants. Slopes defaults to 135, and slants to 154. Required for the player sprite to automatically rotate to match the ceiling angle.
void set_wall_angles(int slant_down_min, int slant_down_max, int slant_up_min, int slant_up_max)
Change which wall surface angles this entity considers down and up facing slants. Down facing defaults to 116, and up facing to 64. Required or wall angles outside of the range slant_up_min < 90 < slant_down_max won’t work, even if the custom collision handler returns a collision.
bool check_collision(tilecollision@ t, int side, bool moving, float snap_offset)
Performs the default collision check on the specified side used by all entities and writes the result into t.
moving indicates if the collision should compensate for movement of the hitbox over the previous subframe (i.e. for checking for collisions between subframes).
snap_offset indicates an additional offset outside of the collision for the entity to look for a surface used in e.g. wall snap jumps/dashes.
Returns true if the collision hits anything.
void set_collision_handler(callback_base@ base_obj, string callback_method, int arg)
Overrides the default tile collision checking for this entity. Setting base_obj to null will clear the handler.
- Arguments:
- base_obj:
The object the callback will be invoked on.
- callback_method:
The name of the function to invoke.
- arg:
An opaque value to be passed back to the callback when invoked.
The callback should have the signature:
void func_name(controllable@ ec, tilecollision@ tc, int side, bool moving, float snap_offset, int arg)
- Callback Arguments:
- ec:
The entity to check collisions for
- tc:
The tile collision object to write results to
- side:
which surface type to check for collisions, see the side_types enum.
- moving:
Indicates if the collision should compensate for movement over the last subframe.
- snap_offset:
Indicates an extra offset to look for collisions used in e.g. snap jumps/dashes
- arg:
The same value that was passed when registering the callback.
Use the provided tilecollision object to return the results of the custom collision.
- Collision Results:
- hit():
Set to true to indicate a collision happened
- type():
Sets the surface angle of the collision (angle() is not used)
- hit_x/y():
The position of the collision
Calling controllable::check_collision can be used to perform the default tile collision handling when needed.
void set_texture_type_handler(callback_base@ base_obj, string callback_method, int arg)
Overrides the default surface texture type lookup for entity. Setting base_obj to null will clear the handler.
The callback should have the signature: void func_name(controllable@, texture_type_query@, int)
See texture_type_query for details.
void stun(float stun_x_speed, float stun_y_speed)
Stuns the controllable. This does not break combo.
float draw_offset_x()
The game offsets the rendering of the sprites when on some surfaces or when stunned (and perhaps more). Added draw_offset_x() and draw_offset_y() to the entity’s actual coordinates if you wish to compensate for this. Note that stun offsets are RNG and shouldn’t affect game play.
float draw_offset_y()
void draw_offset_x(float x_offset)
Set the drawing offsets. This does not include stun offsets.
void draw_offset_y(float y_offset)
int player_index()
Return the player index of this controllable entity. If the entity is not associated with a player returns -1. This is the reverse function of controller_entity(player).
ai_controller@ ai_controller()
Returns the AI controlling this entity.
int filth_type()
Controls the type of dust this entity spread. See enum filth_types for a list of possible values.
void filth_type(int filth_type)
int emitter_filth_type()
Controls the type of emitter created when hit. If set to ‘filth_type_default’ the filth_type value will be used instead.
void emitter_filth_type(int filth_type)
class dustman
Inherits: controllable
float run_accel_over()
void run_accel_over(float run_accel_over)
float dash_speed()
void dash_speed(float dash_speed)
float slope_slide_speed()
void slope_slide_speed(float slope_slide_speed)
float slope_max()
void slope_max(float slope_max)
float land_fric()
Internally this value is not used anywhere.
void land_fric(float land_fric)
float roof_fric()
void roof_fric(float roof_fric)
float skid_threshold()
void skid_threshold(float skid_threshold)
float jump_a()
void jump_a(float jump_a)
float hop_a()
void hop_a(float hop_a)
float fall_max()
void fall_max(float fall_max)
float fall_accel()
void fall_accel(float fall_accel)
float hover_accel()
void hover_accel(float hover_accel)
float heavy_fall_threshold()
void heavy_fall_threshold(float heavy_fall_threshold)
float hover_fall_threshold()
void hover_fall_threshold(float hover_fall_threshold)
float hitrise_speed()
void hitrise_speed(float hitrise_speed)
float di_speed()
void di_speed(float di_speed)
float di_speed_wall_lock()
void di_speed_wall_lock(float di_speed_wall_lock)
float di_move_max()
void di_move_max(float di_move_max)
float wall_slide_speed()
void wall_slide_speed(float wall_slide_speed)
float wall_run_length()
void wall_run_length(float wall_run_length)
float roof_run_length()
void roof_run_length(float roof_run_length)
float attack_force_light()
void attack_force_light(float attack_force_light)
int combo_count()
void combo_count(int combo_count)
int skill_combo()
void skill_combo(int skill_combo)
int skill_combo_max()
void skill_combo_max(int skill_combo_max)
float combo_timer()
void combo_timer(float combo_timer)
int total_filth()
int dash()
Query/set the number of air charges the player has.
void dash(int dash)
int dash_max()
Query/set the maximum number of air charges the player has.
void dash_max(int dash_max)
float dustblock_clear_speed()
Access the speed required to clear dustblocks when falling, as a percentage of ‘fall_max’.
void dustblock_clear_speed(float speed)
rectangle@ dustblock_clear_rect()
Get/set the rectangle relative to the player centre used to clear dustblocks when falling.
void dustblock_clear_rect(rectangle@ rect)
void dustblock_clear_rect(float top, float bottom, float left, float right)
void get_dustblock_clear_rect(float &out top, float &out bottom, float &out left, float &out right)
string character()
Should be one of dustman, dustgirl, dustkid, dustworth, dustwraith, leafsprite, trashking, slimeboss. Optionally add ‘v’ to the start of the name to make it a virtual character. Using the string “default” will return the character choice to what the player initially selected.
void character(string character)
int attack_filth_type()
Controls the type of dust spread when attacking. If set to ‘filth_type_default’ the controllable::filth_type value will be used instead.
void attack_filth_type(int filth_type)
bool ai_disabled()
Normally dustman entities that aren’t attached to a camera are taken over by the default AI implementation. Set this flag to disable this behavior.
void ai_disabled(bool ai_disabled)
bool dead()
Determines if the player is considered ‘dead’. This is useful if you disable auto respawning or want to make the player invincible.
void dead(bool dead)
bool auto_respawn()
Disable the player from respawning on death automatically.
void auto_respawn(bool auto_respawn)
void kill(bool as_spikes)
Simulate the player hitting a death zone if as_spikes=false, otherwise simulate them hitting spikes. Sets the dead flag but doesn’t check if it was already set.
void on_subframe_end_callback(callback_base@ base_obj, string callback_method, int arg)
Set a callback after every substep of this dustman object. The callback should have the signature “void func_name(dustman@ dm, int arg). The ‘arg’ value passed to on_subframe_end_callback will match the ‘arg’ parameter passed to the callback.
class ai_controller
Inherits: entity
class hitbox
Inherits: entity
Note that for dust spread to work correctly after moving a hitbox base_rectangle must be called after setting its position.
controllable@ owner()
hittable@ hittable_owner()
Can be used instead of owner() if the owner is not a controllable, e.g. in the case of a quill.
int damage()
void damage(int damage)
int filth_type()
void filth_type(int filth_type)
bool aoe()
Used to indicate that the force from this hitbox should be applied radially outward from the center rather than using the attack_dir.
void aoe(bool aoe)
float state_timer()
void state_timer(float state_timer)
float activate_time()
void activate_time(float activate_time)
float timer_speed()
void timer_speed(float timer_speed)
float attack_ff_strength()
Attack freeze frame strength. Controls how long the hit entity is frozen.
void attack_ff_strength(float attack_ff_strength)
float parry_ff_strength()
void parry_ff_strength(float parry_ff_strength)
float stun_time()
void stun_time(float stun_time)
bool can_parry()
void can_parry(bool can_parry)
int attack_dir()
void attack_dir(int attack_dir)
float attack_strength()
void attack_strength(float attack_strength)
int team()
void team(int team)
string attack_effect()
void attack_effect(string attack_effect)
int effect_frame_rate()
void effect_frame_rate(int effect_frame_rate)
bool triggered()
int hit_outcome()
See the hit_outcomes enumeration for possible values. This may change after being triggered (e.g. when the player changes state), in which case triggered_outcome can be used.
void hit_outcome(int hit_outcome)
int triggered_outcome()
Returns the outcome when this hitbox triggered, or ho_unresolved if it has not triggered yet.
void on_hit_filter_callback(callback_base@ base_obj, string callback_method, int arg)
Called for each entity this hitbox will potentially hit. Return false to ignore the given entity. The callback should have the signature “bool func_name(hitbox@, hittable@, int)”. The ‘arg’ value passed to on_hit_callback will match the ‘arg’ parameter passed to the callback.
class effect
Inherits: entity
Represents a sprite animation that can optionally move or follow the path of an existing entity.
bool slow_down()
If false the effect will ignore time scale.
void slow_down(bool slow_down)
float scale_x()
void scale_x(float scale_x)
float scale_y()
void scale_y(float scale_y)
void set_scale(float scale_x, float scale_y)
float x_speed()
void x_speed(float x_speed)
float y_speed()
void y_speed(float y_speed)
void set_speed(float x_speed, float y_speed)
entity@ follow_target()
void follow_target(entity@ follow_target)
hittable@ freeze_target()
If not null then the effect will freeze whenever freeze_target is experiencing freeze frames.
void freeze_target(hittable@ freeze_target)
bool follow_x()
If true then the x-coordinate of the follow_target will be followed
void follow_x(bool follow_x)
bool follow_y()
If true then the y-coordinate of the follow_target will be followed
void follow_y(bool follow_y)
void set_follow(bool follow_x, bool follow_y)
string sprite_set()
void sprite_set(string sprite_set)
float state_timer()
void state_timer(float state_timer)
int total_frames()
float frame_rate()
void frame_rate(float frame_rate)
int sub_layer()
void sub_layer(int sub_layer)
uint colour()
void colour(uint b_colour)
class filth_ball
Inherits: entity
Spawned after an enemy is cleaned and calls scene::project_tile_filth when the state timer runs out.
The top/bottom/left/right flags are calculated automatically based on direction, and base_rectangle is used for the ‘baseWidth’ and ‘baseHeight` arguments.
int filth_type()
Controls the type of dust this entity spreads. See enum filth_types for a list of possible values.
void filth_type(int filth_type)
int direction()
See scene::project_tile_filth for a description of this value. The top/bottom/left/right flags will automatically be set based on this.
void direction(int direction)
float distance()
- See scene::project_tile_filth
for a description of this value.
void distance(float distance)
float state_timer()
When this counts down to zero the filth ball will spread dust and remove itself from the scene.
void state_timer(float state_timer)
class scripttrigger
Inherits: entity
Represents a generic script-backed trigger.
trigger_base@ get_object()
Returns the script object backing this trigger. If this object is from a different script than the calling script this will return null instead.
string script_name()
Returns the name of the script this trigger comes from.
string type_name()
Returns the class name of this trigger within its script.
int radius()
Access the radius of the activation circle or square around this trigger. If the trigger has a square shape then the square extends width() out in each direction from the center of the trigger, i.e. it’s side length is 2*width().
void radius(int radius)
int height()
Access the activation area height for rectangular triggers. Will be set to -1 for square triggers. Only applicable when is_square is true.
void height(int height)
bool square()
Access if the trigger has a square or circle activation area.
void square(bool square)
bool editor_show_radius()
Access whether the radius is visible in the editor or not.
void editor_show_radius(bool show_radius)
int editor_handle_size()
Access the size of the trigger handle in the editor. The handle size is how many pixels in each direction the handle should extend, default is 10.
void editor_handle_size(int handle_size)
uint editor_colour_active()
Access the colour of the trigger handle when it is selected.
void editor_colour_active(uint colour)
uint editor_colour_inactive()
Access the colour of the trigger handle when it is not selected.
void editor_colour_inactive(uint colour)
uint editor_colour_circle()
Access the colour of the activation circle/square.
void editor_colour_circle(uint colour)
Use after changing persistent variables via script to update values in the trigger script panel.
bool editor_selected()
bool editor_triggers_visible()
Convenience for checking if triggers are visible in the editor without needing an editor instance.
bool editor_cameras_visible()
Convenience for checking if cameras are visible in the editor without needing an editor instance.
class scriptenemy
Inherits: controllable
Represents a generic script-backed enemy.
enemy_base@ get_object()
Returns the enemy object backing this enemy. If this object is from a different script than the calling script this will return null instead.
string script_name()
Returns the name of the script this enemy comes from.
string type_name()
Returns the class name of this enemy within its script.
bool auto_physics()
void auto_physics(bool auto_physics)
Use after changing persistent variables via script to update values in the enemy script panel.
bool editor_triggers_visible()
Convenience for checking if triggers are visible in the editor without needing an editor instance.
bool editor_cameras_visible()
Convenience for checking if cameras are visible in the editor without needing an editor instance.
class sprites
Represents a set of sprites that can be drawn. Sprites are organized into sprite set files that can be seen in ‘content/sprites’ and can be added into this sprite object using ‘add_sprite_set’ call.
Each sprite set file has a list of sprite names. These names can be enumerated using get_sprite_count(sprite_set) and get_sprite_name(sprite_set, i).
Each sprite name has some number of color palettes (most often it’s just 1) which can be counted using get_palette_count(). They also have some number of frames which you can calculate with get_animation_length().
You can download all of the sprites from https://www.dropbox.com/s/11pa1cdqhv68etv/sprites.rar?dl=0 although the folder structure doesn’t always match the sprite set structure used in game.
void add_sprite_set(string sprite_set)
Add a sprite set’s sprites into this sprites object. After this call we can refer to any contained sprites with draw/get_palette_count/get_animation_length. Any duplicate sprite names will be overwritten to point to the most recently added sprite set.
int get_animation_length(string sprite_name)
Returns the number of frames the named sprite last.
uint get_palette_count(string sprite_name)
Returns the number of palettes associated with the sprite. Tile sprites are typically the only sprites to have multiple palettes.
uint get_sprite_count(string sprite_set)
Returns the number of sprites contained in the sprite set.
string get_sprite_name(string sprite_set, uint index)
Returns the name of the index’th sprite in sprite_set.
rectangle@ get_sprite_rect(string sprite_name, uint32 frame)
Returns the bounding rectangle around the sprite if it were rendered at the origin.
void draw_world(int layer, int sub_layer, string spriteName, uint32 frame, uint32 palette, float x, float y, float rotation, float scale_x, float scale_y, uint32 colour)
Draw a sprite to the world. 1 <= palette <= get_palette_count(spriteName) 0 <= frame < get_animation_length(spriteName)
colour is an ARGB colour vector that is multiplied with the actual color values rendered. This does not include color manipulation through fog colours. Setting colour to 0xFFFFFFFF draws the sprite normally with only fog colour applied.
void draw_hud(int layer, int sub_layer, string spriteName, uint32 frame, uint32 palette, float x, float y, float rotation, float scale_x, float scale_y, uint32 colour)
Like draw_world except drawing in the hud.
class prop
uint id()
Return the ID associated with this prop that can be used with the prop_by_id() function. All props that have been added to the scene should have an ID.
float x()
void x(float x)
float y()
void y(float y)
float rotation()
void rotation(float rotation)
float scale_x()
void scale_x(float scale_x)
float scale_y()
void scale_y(float scale_y)
uint prop_set()
C has an excellent reference to find the prop set/group/index for props which can be found at https://github.com/cmann1/PropUtils/tree/master/files/prop_reference. The three numbers listed under each prop correspond to the set, group, and index for that prop.
void prop_set(uint prop_set)
uint prop_group()
void prop_group(uint prop_group)
uint prop_index()
void prop_index(uint prop_index)
uint palette()
The palette for the prop. Most (all?) props only support palette 1.
void palette(uint palette)
uint layer()
The layer to render the prop in.
void layer(uint layer)
uint sub_layer()
The sublayer to render the prop in.
void sub_layer(uint sub_layer)
class textfield
Represents a text field used to render text to the screen.
string text()
Access the text to be rendered or measured.
void text(string text)
string font()
Get and set the font used to render the text. See https://pastebin.com/YcNKSXd9 for a list of supported fonts and font sizes.
uint font_size()
void set_font(string font, uint font_size)
uint colour()
Set the colour of the text as an ARGB value.
void colour(uint colour)
int align_horizontal()
Set the horizontal alignment when drawing the text. -1 aligns the left of the text to the given x coordinate. 0 centers the text at the given x coordinate. 1 aligns the right of the text to the given x coordinate.
void align_horizontal(int align_h)
int align_vertical()
Set the vertical alignment when drawing the text. -1 aligns the top of the text to the given y coordinate. 0 centers the text at the given y coordinate. 1 aligns the bottom of the text to the given y coordinate.
void align_vertical(int align_v)
int text_width()
Measures the width of the text when drawn.
int text_height()
Measures the height of the text when drawn.
void draw_world(int layer, int sub_layer, float x, float y, float scale_x, float scale_y, float rotation)
void draw_hud(int layer, int sub_layer, float x, float y, float scale_x, float scale_y, float rotation)
class varvalue
A common interface used to represent a variable of any type.
int type_id()
Returns the type of the variable. See ‘var_types’ at the end of this documentation for details on the different types.
bool get_bool()
Get or set the value. The getter or setter used must match the type_id() of the var.
void set_bool(bool val)
int8 get_int8()
void set_int8(int8 val)
int16 get_int16()
void set_int16(int16 val)
int32 get_int32()
void set_int32(int32 val)
int64 get_int64()
void set_int64(int64 val)
float get_float()
void set_float(float val)
string get_string()
void set_string(string val)
float get_vec2_x()
float get_vec2_y()
void set_vec2(float x, float y)
varstruct@ get_struct()
Returns a modifiable handle to the struct pointed to by this var.
vararray@ get_array()
Returns a modifiable handle to the array pointed to by this var.
class vararray
Represents an array of variables.
varvalue@ at(uint32 index)
Get the i-th value in this array. Returns null for indicies outside the bounds of the array.
int element_type_id()
Returns the element type of this array.
uint32 size()
Returns the size of this array.
void resize(uint32 size)
Resizes this array. If the array size is extended the new elements are not initialized.
class varstruct
Represents a dictionary of string keys to vars.
varvalue@ get_var(string var)
Retrieves a var based on its name.
varvalue@ get_var(uint32 index)
Retrieves the index’th var.
uint32 num_vars()
Returns the number of vars in this struct.
string type_name()
Returns the type name of the struct.
string var_name(uint32 index)
Returns the name of the index’th var.
class message
int get_int(string key)
int get_int(string key, int def)
void set_int(string key, int val)
bool has_int(string key)
uint num_int()
string get_key_int(uint index)
float get_float(string key)
float get_float(string key, float def)
void set_float(string key, float val)
bool has_float(string key)
uint num_float()
string get_key_float(uint index)
string get_string(string key)
string get_string(string key, string def)
void set_string(string key, string val)
bool has_string(string key)
uint num_string()
string get_key_string(uint index)
entity@ get_entity(string key)
void set_entity(string key, entity@ e)
bool has_entity(string key)
uint num_entity()
string get_key_entity(uint index)
class var_info
string get_name()
Returns the name of the variable that changed
int get_index()
Returns the index that was changed, or -1 if this variable is not an array
int get_path_length()
For nested variables returns the number of variables above this one
string get_name(uint index)
Returns the name of the parent variable at the specified level
int get_index(uint index)
Returns the array index of the parent variable at the specified level, or -1 if it is not an array
string get_path(bool include_array_indices)
Convenience method that returns the entire path as a string in the format: “parent_var.parent_var2.var” If include_array_indices is true, arrays in the path will also include an index, e.g. “parent_var[i]”
class texture_type_query
Certain sounds, e.g. player footstep sounds, check the tiles around the player’s feet to determine which sounds to play based on the tile sprite set and index. controllable::set_texture_type_handler can be used to bypass that behaviour and provide a custom texture type.
This class is used to pass values back and forth during a texture type callback registered with controllable::set_texture_type_handler.
int x()
The location to check
int y()
The location to check
bool top_surface()
Is the query for a ground surface?
string result()
void result(string result)
Set this to return the texture type or use an empty string to use the default texture lookup.
Valid textures are “none”, “stone”, “dirt”, “metal”, “grass” “water”, “wood”, “carpet”, or “poly”.
class canvas
A configurable drawing surface that supports affine transformations.
The transformaton matrix is stored in the form
[x'] [m00 m01 ox] [x] [y'] = [m10 m11 oy] [y] [1 ] [0 0 1 ] [1]bool hud()
Access whether this canvas draws to the hud or world.
void hud(bool hud)
int layer()
Access what layer this canvas draws to.
void layer(int layer)
int sub_layer()
Access what sub layer this canvas draws to.
void sub_layer(int sub_layer)
void draw_rectangle(float x1, float y1, float x2, float y2, float rotation, uint colour)
These draw routines mirror the existing draw routines using the canvas specific options and transformation.
void draw_glass(float x1, float y1, float x2, float y2, float rotation, uint colour)
void draw_gradient(float x1, float y1, float x2, float y2, uint c00, uint c10, uint c11, uint c01)
void draw_line(float x1, float y1, float x2, float y2, float width, uint colour)
void draw_quad(bool is_glass, float x1, float y1, float x2, float y2, float x3, float y3, float x4, float y4, uint c1, uint c2, uint c3, uint c4)
void draw_sprite(sprites@ spr, string spriteName, uint32 frame, uint32 palette, float x, float y, float rotation, float scale_x, float scale_y, uint32 colour)
void draw_text(textfield@ txt, float x, float y, float scale_x, float scale_y, float rotation)
void transform_point(float x, float y, float &out tx, float &out ty)
Compute the x/y coordinates of the underlying canvas transform.
void multiply(float m00, float m01, float m10, float m11, float ox, float oy)
Right multiply a generic affine matrix.
void multiply_left(float m00, float m01, float m10, float m11, float ox, float oy)
Left multiply a generic affine matrix.
void scale(float scale_x, float scale_y)
Each transformation option has a right (default) and left multiply variant. A right multiply transformation is applied to the source coordinates, a left multiply is applied to the transformed coordinates.
void scale_left(float scale_x, float scale_y)
void translate(float ox, float oy)
void translate_left(float ox, float oy)
void rotate(float degrees, float center_x, float center_y)
void rotate_left(float degrees, float center_x, float center_y)
void push()
Push the current transform settings onto a stack. pop() can later be used to return these settings. Note that this only affects the transform settings of this canvas.
void pop()
void reset()
Reset the transform to the identity transform and clear the transform stack.
bool scale_hud()
Control whether or not the coordinates should be auto-scaled to simulate a 1600-900 sized screen. Only changes behavior for hud canvases. By default this is set to true.
void scale_hud(bool scale_hud)
class emitter_type
Represents a global emitter type.
uint get_id()
Returns the id of this emitter type.
string get_name()
Returns the name of this emitter type.
bool get_burst()
Access whether this emitter type is a “burst” emitter. Burst emitters will automatically remove themselves from the scene after a short period of time.
void set_burst(bool burst)
uint get_particle_type_count()
Returns the number of particle types added to this emitter type.
int add_particle_type(particle_type@ particle_type)
Adds the given particle type to this emitter type. Returns the index of newly added particle type or -1 if the particle type was not valid.
int add_particle_type(uint index)
Adds the particle type with the given index to this emitter type. Returns the index of newly added particle type or -1 if the particle type was not valid.
void remove_particle_type_at(uint index)
Removes the particle type from this emitter type at the given index.
particle_type@ get_particle_type_at(uint index)
Returns the particle type for this emitter type at the given index, or null if the index is invalid.
void get_density(uint index, float &out value, float &out range)
Returns the density value and range for the particle type at the given index.
void set_density(uint index, float value, float range)
Sets the density value and range for the particle type at the given index.
void get_speed(uint index, float &out value, float &out range)
Returns the speed value and range for the particle type at the given index.
void set_speed(uint index, float value, float range)
Sets the speed value and range for the particle type at the given index.
void get_direction(uint index, float &out value, float &out range)
Returns the direction value and range for the particle type at the given index.
void set_direction(uint index, float value, float range)
Sets the direction value and range for the particle type at the given index.
class particle_type
Represents a global emitter particle type.
uint get_sprite_count()
Returns the number of sprites added to this particle type.
string get_sprite_at(uint index)
Returns the sprite name at the given index, or an empty string if the given index is invalid.
void add_sprite(string sprite)
Add a new sprite to this particle type.
void remove_sprite_at(uint index)
Removes the sprite at the given index.
void clear_sprites()
Removes all sprites for this particle type.
float get_frame()
void set_frame(float frame)
float get_frame_range()
void set_frame_range(float frame_range)
void get_frame(float &out value, float &out range)
void set_frame(float value, float range)
bool get_loop_animation()
void set_loop_animation(bool loop_animation)
float get_frame_speed()
void set_frame_speed(float frame_speed)
float get_frame_speed_range()
void set_frame_speed_range(float frame_speed_range)
void get_frame_speed(float &out value, float &out range)
void set_frame_speed(float value, float range)
float get_rotation_speed()
void set_rotation_speed(float rotation_speed)
float get_rotation_speed_range()
void set_rotation_speed_range(float rotation_speed_range)
void get_rotation_speed(float &out value, float &out range)
void set_rotation_speed(float value, float range)
float get_rotation()
void set_rotation(float rotation)
float get_rotation_range()
void set_rotation_range(float rotation_range)
void get_rotation(float &out value, float &out range)
void set_rotation(float value, float range)
bool get_flip_x()
void set_flip_x(bool flip_x)
bool get_flip_y()
void set_flip_y(bool flip_y)
float get_scale()
void set_scale(float scale)
float get_scale_range()
void set_scale_range(float scale_range)
void get_scale(float &out value, float &out range)
void set_scale(float value, float range)
float get_x_scale()
void set_x_scale(float x_scale)
float get_x_scale_range()
void set_x_scale_range(float x_scale_range)
void get_x_scale(float &out value, float &out range)
void set_x_scale(float value, float range)
float get_x_scale_end()
void set_x_scale_end(float x_scale_end)
float get_x_scale_end_range()
void set_x_scale_end_range(float x_scale_end_range)
void get_x_scale_end(float &out value, float &out range)
void set_x_scale_end(float value, float range)
float get_y_scale()
void set_y_scale(float y_scale)
float get_y_scale_range()
void set_y_scale_range(float y_scale_range)
void get_y_scale(float &out value, float &out range)
void set_y_scale(float value, float range)
float get_y_scale_end()
void set_y_scale_end(float y_scale_end)
float get_y_scale_end_range()
void set_y_scale_end_range(float y_scale_end_range)
void get_y_scale_end(float &out value, float &out range)
void set_y_scale_end(float value, float range)
float get_life()
void set_life(float life)
float get_life_range()
void set_life_range(float life_range)
void get_life(float &out value, float &out range)
void set_life(float value, float range)
float get_gravity()
void set_gravity(float gravity)
float get_gravity_direction()
void set_gravity_direction(float gravity_direction)
float get_x_friction()
void set_x_friction(float x_friction)
float get_y_friction()
void set_y_friction(float y_friction)
float get_wind_scale()
void set_wind_scale(float wind_scale)
float get_wind_scale_range()
void set_wind_scale_range(float wind_scale_range)
void get_wind_scale(float &out value, float &out range)
void set_wind_scale(float value, float range)
class timedate
Definitions match those described in http://www.cplusplus.com/reference/ctime/tm/
int sec()
int min()
int hour()
int mday()
int mon()
int year()
int wday()
int yday()
int isdst()
class fog_setting
void copy_from(camera@ camera)
Copies the settings from the given camera.
void copy_from(entity@ trigger)
Copies the settings from the given fog trigger. Does nothing if the entity is null or not a fog trigger.
void copy_from(fog_setting@ other)
Copies the settings from the given fog_setting.
void copy_to(entity@ trigger)
Copies the settings from this settings object to the given fog trigger.
uint colour(uint layer, uint sublayer)
Access the layer and sublayer fog colours. sublayer is ignored if this ettings object does not have sub layers.
void colour(uint layer, uint sublayer, uint colour)
void default_colour(uint layer, uint colour)
Set the default sublayer colour.
uint layer_colour(uint layer)
Get the default sublayer colour.
void layer_colour(uint layer, uint colour)
Set the colour for all sublayers on the given layer.
float percent(uint layer, uint sublayer)
Access the layer and sublayer fog percents. The percent for each layer/sublayer indicates how to mix the fog colour with the graphics on that layer. A percent of 0 ignores the fog colour and a percent of 1 replaces all colours in drawn graphics with the fog colour. sublayer is ignored if this ettings object does not have sub layers.
void percent(uint layer, uint sublayer, float percent)
void default_percent(uint layer, float percent)
Set the default sublayer percent.
float layer_percent(uint layer)
Get the default sublayer percent.
void layer_percent(uint layer, float percent)
Set the percent for all sublayers on the given layer.
float bg_mid_point()
Access where on the screen the screen the middle background colour is rendered. Should be between 0 and 1 with 0 indicating the top of the screen and 1 the bottom.
void bg_mid_point(float bg_mid_point)
uint bg_top()
Access the background colour at the top of the screen.
void bg_top(uint bg_top)
uint bg_mid()
Access the background colour in the middle of the screen.
void bg_mid(uint bg_mid)
uint bg_bot()
Access the background colour at the bottom of the screen.
void bg_bot(uint bg_bot)
float stars_top()
Access the star saturation at the top of the screen. Should be a number between 0 and 1.
void stars_top(float s_top)
float stars_mid()
Access the star saturation in the middle of the screen.
void stars_mid(float s_mid)
float stars_bot()
Access the star saturation at the bottom of the screen.
void stars_bot(float s_bot)
bool has_sub_layers()
void has_sub_layers(bool has_sub_layers)
Convert this fog_setting object between normal and sublayer.
class editor_api
bool key_check_vk(int vk)
Deprecated. Use class input_api instead.
bool key_check_pressed_vk(int vk)
Deprecated. Use class input_api instead.
bool key_check_gvb(int gvb)
Deprecated. Use class input_api instead.
bool key_check_pressed_gvb(int gvb)
Deprecated. Use class input_api instead.
void key_clear_gvb(int gvb)
Deprecated. Use class input_api instead.
bool key_check_vb(int player, int vb)
Deprecated. Use class input_api instead.
bool key_check_pressed_vb(int player, int vb)
Deprecated. Use class input_api instead.
void key_clear_vb(int player, int vb)
Deprecated. Use class input_api instead.
bool has_focus()
Deprecated. Use class input_api instead.
bool is_polling_keyboard()
Deprecated. Use class input_api instead.
bool poll_keyboard()
Deprecated. Use class input_api instead.
string editor_tab()
Return the currently active editor tab.
bool editor_tab(string tab_name)
Returns true if the change succeeded.
int get_selected_layer()
Returns the selected layer.
void set_selected_layer(int layer)
Sets the selected layer.
int get_selected_sub_layer()
Returns the selected sub layer for props.
void set_selected_sub_layer(int sub_layer)
Sets the selected sub layer for props.
bool get_layer_visible(int layer)
Returns true if the given layer is visible.
void set_layer_visible(int layer, bool visible)
Sets the visibility of the given layer.
bool get_layer_locked(int layer)
Returns true if the given layer is locked.
void set_layer_locked(int layer, bool visible)
Sets the locked state of the given layer.
bool check_layer_filter(int layer)
Returns true if the given layer is visible and not locked.
bool check_layer_filter(int layer, int sub_layer)
Returns true if the given sublayer is visible and not locked.
bool triggers_visible()
Returns false if triggers are hidden in the editor. Triggers should check this during editor_draw to disable any editor related drawing.
bool cameras_visible()
Returns false if cameras are hidden in the editor.
entity@ get_selected_trigger()
Returns the selected trigger.
void set_selected_trigger(entity@ trigger)
Set the selected trigger.
entity@ get_selected_entity()
Returns the selected entity.
void set_selected_entity(entity@ entity)
Set the selected entity.
bool help_screen_vis()
Access whether the help menu is visible.
void help_screen_vis(bool vis)
bool hide_gui()
void hide_gui(bool hide)
bool hide_panels_gui()
void hide_panels_gui(bool hide)
bool hide_toolbar_gui()
void hide_toolbar_gui(bool hide)
bool hide_layers_gui()
void hide_layers_gui(bool hide)
bool mouse_in_gui()
Returns true if the mouse is within the editor GUI menus
void force_mouse_in_gui()
Force the editor to act as if the mouse is inside of the GUI menu for the remainder of the frame
Returns the width of the left menu panel.
Returns the width of the right menu panel.
rectangle@ select_rectangle()
uint selected_entity_count()
Return the number of selected entities.
entity@ selected_entity(uint index)
Return the index-th selected entity or null if no entity exists at that index.
uint selected_prop_count()
Return the number of selected props.
prop@ selected_prop(uint index)
Return the index-th selected prop or null if no prop exists at that index.
void get_tile_sprite(int &out sprite_set, int &out sprite_tile, int &out sprite_palette)
Return the selected tile set, index, and palette used by the tile tool.
void set_tile_sprite(int sprite_set, int sprite_tile, int sprite_palette)
Sets the selected tile set, index, and palette used by the tile tool.
void get_prop(int &out prop_set, int &out prop_group, int &out prop_index, int &out prop_palette)
Return the selected prop set, group, index, and palette used by the prop tool.
void set_prop(int prop_set, int prop_group, int prop_index, int prop_palette)
Sets the selected prop set, group, index, and palette used by the prop tool.
class input_api
string get_text()
Returns text input recorded over the last frame.
void set_text(string text)
string get_clipboard()
Returns the clipboard text.
bool set_clipboard(string text)
Returns false on failure??
float mouse_x_hud(bool scale)
Returns the x coordinate of the mouse in the hud coordinate space. If scale is set to true will auto scale the coordinates to simulate a 1600-900 screen size. Will range between -width/2 and width/2.
float mouse_x_hud()
Equivalent to mouse_x_hud(false)
float mouse_y_hud(bool scale)
Returns the y coordinate of the mouse in the hud coordinate space. If scale is set to true will auto scale the coordinates to simulate a 1600-900 screen size. Will range between -height/2 and height/2.
float mouse_y_hud()
Equivalent to mouse_y_hud(false)
float mouse_x_world(int layer)
Returns the x coordinate of the mouse for the given layer.
float mouse_y_world(int layer)
Returns the y coordinate of the mouse for the given layer.
void mouse_world(int layer, int sub_layer, float &out x, float &out y)
Returns the coordinates of the mouse for the given layer and sublayer.
float screen_width()
Return the current screen width in pixels.
float screen_height()
Return the current screen height in pixels.
int mouse_state()
Returns the mouse state as a bitmask. The bits correspond to the following button states:
- Bitmask:
- 0x1:
wheel up
- 0x2:
wheel down
- 0x4:
left down
- 0x8:
right down
- 0x10:
middle down
- 0x20:
left pressed
- 0x40:
right pressed
- 0x80:
middle pressed
- 0x100:
left release
- 0x200:
right release
- 0x400:
middle release
int gvb_to_vk(const int gvb)
Converts the given global virtual button to a virtual key code. Returns -1 if gvb is not a valid button.
int vk_to_gvb(const int vk)
Converts the given virtual key code to a global virtual button. Returns -1 if the given key is not mapped to a virtual button.
bool key_check_vk(int vk)
Returns true if the key is currently pressed. vk should be a virtual key keycode. See https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes. This is raw access to the underlying key state and will never work in net games. Button states should only be accessed in step() functions.
bool key_check_pressed_vk(int vk)
Returns true if the key was pressed this frame.
bool key_check_released_vk(int vk)
Returns true if the key was released this frame.
bool key_check_double(int vk)
Returns true if the key was double tapped.
bool key_check_gvb(int gvb)
Returns true if the “global virtual button” is currently pressed. Refer to the GLOBAL_VIRTUAL_BUTTON enum for options for this value. These button states are fully managed in net games.
bool key_check_pressed_gvb(int gvb)
Returns true if the global virtual button is pressed this frame.
bool key_check_released_gvb(int gvb)
Returns true if the global virtual button is released this frame.
void key_clear_gvb(int gvb)
Unset the global virtual button state.
bool key_check_vb(int player, int vb)
Returns true if the “player virtual button” is currently pressed. Refer to the PLAYER_VIRTUAL_BUTTON enum for options for this value. These button states are fully managed in net games.
bool key_check_pressed_vb(int player, int vb)
Returns true if the global virtual button is pressed this frame.
void key_clear_vb(int player, int vb)
Unset the global virtual button state.
bool has_focus()
Returns true if a UI control has focus
bool is_polling_keyboard()
Returns true if a UI control, e.g. a text box, is taking keyboard input
bool poll_keyboard()
Polls the keyboard for one frame, blocking shortcuts such as frame advance
class nexus_api
API methods useful within a nexus. These allow you to access/modify information about used keys and what levels have been completed within the nexus.
Internally, Dustforce tracks two types of information within a nexus.
Key usage information. This information is updated whenever you open a new door.
Level completion information. This includes information about highest ranking score/completion, best time, and what key type the level granted.
Notably keys earned and keys available are not tracked directly and are just a function of the above two pieces of information. The game also keeps track of what doors have been opened by inserting level score data when the level is first opened that has completion and finesse each set to -1.
void get_keys_used(int &out wood, int &out silver, int &out gold, int &out red, bool &out ngplus)
Get the number of keys that have been used of each time. This reflects directly what is persisted to disk. ngplus controls whether all doors are automatically in an open state.
void set_keys_used(int wood, int silver, int gold, int red, bool ngplus)
Update key usage and save to disk.
void get_keys_earned(int &out wood, int &out silver, int &out gold, int &out red)
Convenience function to calculate number of keys that have been earned of each type. Subtract out the used key counts to get the number of available keys.
uint score_count()
Get count of levels that have score data in this nexus root
string score_level(uint index)
Get the name of the i-th level in this nexus root
bool score_lookup(string level, int &out thorough, int &out finesse, float &out time, int &out key_type)
Lookup the score data for a given level.
- Arguments:
- level:
The name of the level to lookup
- thorough:
The “completion” score 1-5 mapping to D-S. -1 indicates the level door has been opened but has not be completed.
- finesse:
The “finesse” score with the same semantics as thorough.
- time:
The fastest completion time for the level. Dustforce tracks this although does nothing with this information natively.
- key_type:
The type of key rewarded for beating the level. 0=none, 1=silver, 2=gold, 3=red, 4=wood.
- Returns:
True if an entry was found for the level and the out variables have been set.
void score_set(string level, int thorough, int finesse, float time, int key_type)
Set the score data for a given level. Variables have the same semantics as in score_lookup.