Concepts

Sucata game engine is data-driven, which means that you can create your game using only Lua scripts. The engine will load the scripts and run them, and you can create relational entities that will interact with each other.

It's highly recommended to use classic library to create classes for your entities, but it's not mandatory, you can create your entities using plain tables if you prefer

Scene

A scene is a pool of entities, and it's the main way to organize your game, you can active a scene to load its entities.

Relationships

The engine don't have hirarchy of entities, instead all entities have relationships with each other, and you can use the unique id of the entities to reference them, and create relationships between them.

For example:

local children_id = sucata.scene.spawn(Bullet())
self.children = children_id

In this example, we are spawning a new entity of type Bullet and storing its unique id in the children field of the current entity, so we can reference it later.

local bullet_entity = sucata.scene.find_by_id(self.children)
bullet_entity.x = self.x
bullet_entity.y = self.y

Entity

An entity is a table that contains data, and some functions that can be called by the engine, every entity spawned will have an unique id, that you can use to reference it.

Data

id

The unique id of the entity, generated by the engine when the entity is spawned.

Functions

This are functions that you can define in your entity, and the engine will call them at the right time.

All function will have 'Self' as a parameter and it is the entity itself, and you can use it to access the data of the entity.

init(self)

Called when the scene is loaded

This function will be called only once.

This function is optional, and you can omit it if you don't need execute any code when the entity is loaded.

update(self)

Called every frame to update the entity

You can call sucata.time.get_delta() to get the time since the last frame, and use it to update the entity's data.

This function is optional, and you can omit it if you don't need execute any code every frame that the entity is loaded.

draw(self)

Called every frame to draw the entity

Normally used to draw graphics for the entity, using sucata.graphics functions.

This function is optional, and you can omit it if you don't need to draw any graphics for the entity.

free(self)

Called when the scene is unloaded

This function will be called only once, right before the entity is removed from the scene.

This function is optional, and you can omit it if you don't need to execute any command before the entity is removed from the scene.