Castagne Engine

Documentation (Dev Branch)

Castagne Engine

Getting Started




Making a Game

Pushing Castagne



This page is in construction! It is marked for review/completion for version 54.

Language Specification

This guide covers how the Castagne Script language works (.casp files), and is a recommended read when starting out.

The language is set to have an upgrade in v0.7, with the rewrite of the compiler.

The current compiler (more like a parser) is already working overtime compared to the initial draft in v0.2, so you may find plenty of bugs and weird behavior if you try to find the edge cases.

Castagne at its core works by treating characters as state machines, where every state can represent an attack, a movement option, a hit state, or whatever else. To know what to do during each, it executes a state script, which is created in Castagne Script.

Example syntax:

# Comment
## State Comment. These are shown on the navigation panel.


    Hitbox(-500, 20000, 5000, 10000)


Castagne Script has two basic types of instructions:

It is possible to add comments by starting a line with #.

During a loop, Castagne goes through several phases, and each state script will be precompiled for each phase. The full list is available in the Engine Core advanced documentation page, but the most important for us are:

In most cases, as a user, all you need to think about is the action phase. The init phase is mostly contained in states starting by Init-, and the reaction phase is handled by the base skeleton.

Some state scripts are given special treatment by the engine, and may be recognized by their names:

Casp files can hold several entities. One of them is the Main entity and serves as a default one, while others are signaled by using the NAME-- prefix.

It is not necessary for a state to be meant to be executed alone, and the language provides some tools to help flag them.

A file can include a Skeleton attribute in the Character script. This is a reference to another file that may be loaded beforehand. States from files loaded later can override those with the same name, allowing them to extend or replace behavior. By default, Castagne will load the base skeleton, but this can be stopped by setting the value to none.

Castagne Script is meant to be worked on in concert with the Castagne Editor, and thus can feature a few QoL features to that effect. While possible to edit Castagne Script in a different text editor, it is recommended to use the one provided by the Castagne Editor (this behavior may be supported more in the future).

Branch Types

The branch types are as follows:







A variable declaration follows the syntax given here:


# Example
var WalkSpeed int() = 500
internal _PositionX

Mutability is a key part of the variable, and changes how it is used and treated by the engine.

Type is the other key part of the variable, and can be either one of:

Variables can be declared in variable declaration blocks. These are defined by their name stating with Variables-, or just being Variables (referred to as the main variable block), in order to help with organization. Variables can't be declared in two different blocks.

Variables of mutability def have some specific behaviors:

Variables can be set using the Set family of functions of the Core module.


Each state may hold a reference to another file, called the skeleton. This allows a character to start from a common base to other characters, and as such reduce development time. This is also very useful for system mechanics

The Skeleton is set in the Character block and can be either of those values:

The compiler will load every file in memory, and start compiling in reverse order, starting by the last skeleton and finishing with the main file. Files compiled later may override parts of the earlier ones as follows:

The skeletons may be set inside the config menu, and the base skeleton has its own documentation page for its features.


A .casp file may hold several entities at once, which is useful for projectiles for instance.

Every file has a Main entity, which is the considered the default one in situations where no sub-entity is specified. Every entity may have its own variables and states, which are going to be used by the compiler when working it out.

Marking to which entity a specific state script belongs to is done through its name. With ENAME as the name of the entity, the convention is as follows:

This is made easier through the entity templates in the editor.

To create a new entity, one must use CreateEntity(ENAME) from the Core module, which will automatically look for these states.

Helpers and Warnings

Castagne Script in practice can be full of "gotchas", small insidious mistakes that can be easy to make and hard to spot (for instance, forgetting to call the code that handles being hit). Therefore, in order to make this easier, the editor has a few quality of life features which have some support in the language.

A lot of this support is done through the Editor module, which provides functions that are not executed but serve to flag properties for the editor. These start with _ by convention and may be ignored for code comprehension.

More of these may be found in the Editor Guide and the Editor Module documentation


Castagne Script is made to be able to be run in parallel, and as such can't access immediate parameters from other entities, nor set them immediately. Inter-entity communication functions are available in the Core Module.

It is meant to be compiled as bytecode, although this is not done at the moment. (v0.7 rewrite)

In the text file format, the states are separated by :StateName: lines.

Editing the files outside of the editor is possible, but not supported by the engine in a nice way. This may be improved in future versions but is not a priority.

The compiler does some optimizations, which are detailed in the Castagne Compiler page.