Data Files
Easel can import data from JSON and CSV files.
This allows you to author content using your favorite tools and then include them in your game.
For example,
- You could use a level editor like Tiled to create your game levels and then export them
as
JSONfiles to use in your game. - You could use a sprite animation tool like Spine to create your character animations and then export them
as
JSONfiles to use in your game. - You could use a spreadsheet program like Google Sheets to create a table of all your game's special abilities,
and then export it as a
CSVfile to use in your game.
Raw import
The declaration below imports data from level1.json into a variable called Level1Data:
pub import Level1Data from @level1.json
This imports the data as-is, without any conversion.
Notably, if you are importing a JSON file, all keys will be Strings, not Symbols,
which means you must use Level1Data["entities"] instead of Level1Data.entities to access a field.
The data file name (e.g. @level1.json) will be found using the same rules as any Asset in Easel.
That is, the file with the given name that is closest to the current file will be selected,
and you can use folder paths to disambiguate between files with the same name.
Schema import
A JSON file can only consist of basic types like Strings and Numbers.
To take advantage of the full gamut of Easel's types,
you can use the as keyword to the imported data according to a given schema:
pub import Level1Data from @level1.json as {
width as Number,
height as Number,
entities as [{
type as Symbol,
image as Asset,
pos = @(x, y),
}],
}
Because this import has a schema, you can now access the data using Level1Data.entities[0].type
instead of Level1Data["entities"][0]["type"].
See Schemas for more information on how to define schemas.
If the data in the file does not match the schema you specify, Easel will throw a compile-time error. This helps you design data files and schemas that are consistent with each other.
Import parameters
You can specify how your data file will be imported by wrapping the asset filename
in a parser function like Csv() or Json(), and providing extra parameters:
pub import CollisionData from Csv(@collision.csv, headers=false, delimiter=';') as [[Number]]
See the corresponding JSON or CSV documentation for more information on the available parameters for each parser function.
As the data file import is performed at compile time,
the parsing functions Csv and Json only work with the import statement,
and are not available at runtime.
Imported data is static
All data imported from files is static. This means that you cannot modify the data at runtime. That is, you cannot add, change or remove elements from Arrays or Maps that have been imported from data files.
pub import WiseSayings from @wiseSayings.json as [String]
pub fn Example1() {
WiseSayings.Push("This will throw an error because imported data is static")
WiseSayings[11] = "This will also throw an error because imported data is static"
}
Because Easel knows for sure this data never changes, this improves performance because Easel can exclude the data from the rollback state.
Supported file formats
These are the only supported file formats at this time. Click on the links to see more information about each format.