This page describes low-level information specific to the loading process of a level. When a level is opened, Warp Factory first runs a file called setup.lua that must be present in the level directory. This file is responsible for setting up various information intrinsic to the level:
It specifies which scripts should run while the level is open.
It defines the in-game menu.
It defines which assets are loaded (e.g. what blocks are present)
It defines the instruction menu.
Typically, these functions are handled indirectly by using setup_utility.lua in the scripts library. The information below is only relevant for someone implementing lower level routines.
Global State
keys
The global variable keys contains a dictionary of all values associated with the state start_save.
LoadHandle
The class LoadHandle is the primary handle through which setup.lua conveys the information necessary to load a level.
Member Functions
int add_block_base(string path)
Loads a base block texture, returning its index. These are the typical kinds of texture one might add to a level.
int add_block_overlay(string path)
Loads a base block texture, returning its index. These textures are rendered on top of blocks when specified - similar to how conveyors are rendered on top of a base texture. Note that any place in the texture where the red channel is much greater than the alpha channel will cause a transparent pixel to be rendered in the combined block (whereas other pixels are overlayed as usual).
int add_normal_overlay(string path)
Loads a normal overlay texture, returning its index. These are used to override the shading of objects. The image should consist of unit inwards normals, scaled so that the range [-1, 1] of possible coordinates is mapped linearly to RGB space. The alpha channel acts as usual, blending the overlaid normals with the standard ones.
void set_lighting_texture(string path)
Sets the texture to use for global lighting of the level. Defaults to the CircularLighting.png file in Resources/Images/Misc.
string? open_text(string path)
Searches for and reads a .lua file. Looks in the level directory, as well as the script library. Returns nil if no file is found.
Specifies that a script should be run on the user side. This script will be run each time the game state is refreshed - which occurs upon resizing the level, loading the level from a file, or restarting the level after starting simulation.
The optional argument arg must be a serializable value and can be accessed from the run script as arg.
Scripts are run in the order that they are added, with all user scripts running before any physics scripts.
Specifies that a script should be run on the physics side. This script will be run each time the game state is refreshed - which occurs upon resizing the level, loading the level from a file, or restarting the level after starting simulation.
The optional argument arg must be a serializable value and can be accessed from the run script as arg.
Scripts are run in the order that they are added, with all user scripts running before any physics scripts.
void set_default_size(int width, int height)
If the level is being loaded without an existing save and there is no file named start_save in the level directory, this function specifies that the loaded level will be an empty grid of the given width and height. Note that there is an invisible two block thick area around the usable region; thus builder:set_default_size(5, 5) would only yield a working area of 1 x 1.
Adds a section to the information tab. The argument title is the label for the tab. The list elements specifies the content to display for that tab.
void set_user_blocks(vector<int> blocks)
Sets which basic blocks can be placed by the user; sending a value of {0} would only allow the usual gray blocks to be placed. The values to be placed in this list are the returns from calls to add_block_base
Requests that the game render the result of interactions and stores this in an image for use in the info panel. Note that at least one block must be placed in the interaction, otherwise an error will occur. Returns the image along with its width and height.
Game Menu
MenuEntry
Constructors
MenuEntry.new(string image, MenuAction action)
Creates a menu entry which will display the image given by image (which must be in the texture atlas for the menu - cannot be loaded from anywhere) and which will, when clicked, perform the action specified by action.
Members
string image
The name of the image to display in the menu.
MenuAction action
The action to perform when clicked.
MenuAction
A variant referring to a value of type UserAction or string. Values of type string are just scripts that will run when the button is clicked.
Info Menu
The following classes relate to the specification of info panels.
InfoElement
A variant referring to a value of type Figure, Prose, or Title.
Figure
A custom element of an info panel including images and text in a specified layout.
Creates a figure of the given height with the given elements. The elements of the figure should be specified relative to a coordinate system in which the figure occupies [-1, 1] x [0, height]. The coordinate (-1, 0) is the bottom left and (1, height) is the top right.
Members
float height
The height of the figure.
vector<FigureElement> items
The list of items in the figure.
Prose
An element of text in paragraph form in an info panel.
Constructors
Prose.new(string text)
Creates a section of description to include in an info panel. Formatted as a paragraph.
Members
string text
The text of the element.
Title
A large centered text element in an info panel.
Constructors
Title.new(string text)
Creates a title to include in the info panel. Displayed in large text and centered in info panel.
Members
string text
The text of the element.
FigureElement
A variant referring to a value of type FigureItem or FigureText.
Creates a figure item with the given image at the given position (relative to the figure). Color values in the texture will be multipled by the color argument if specified.