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.
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)
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¶
string map_name()
Get the current level name.
int level_type()
Get the current level type.
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 spieks 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.
void layer_visible(uint 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.
void layer_scale(uint layer, float scale)
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.
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)
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¶
string camera_type()
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.
void controller_mode(int controller_mode)
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)
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.
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.
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 collisio.
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.
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 a effect object. Returns null if the entity is not a effect 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.
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)
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()
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).
class dustman¶
Inherits: controllable
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 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 idle_fric()
void idle_fric(float idle_fric)
float skid_fric()
void skid_fric(float skid_fric)
float land_fric()
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)
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)
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 hitbox¶
Inherits: entity
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.
void hit_outcome(int hit_outcome)
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 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.
bool editor_selected()
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)
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.
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.
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 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¶
uint colour(uint layer, uint sublayer)
Access the layer and sublayer fog colours.
void colour(uint layer, uint sublayer, uint colour)
void layer_colour(uint layer, uint colour)
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.
void percent(uint layer, uint sublayer, float percent)
void layer_percent(uint layer, float percent)
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)
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.
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.
entity@ get_selected_trigger()
Returns the selected trigger.
entity@ get_selected_entity()
Returns 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.
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.
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
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_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.