Tramway SDK 0.0.9
Github
Quick links
Home
Get Started
Entity
Entities are one of the main concepts of the framework. An entity is a thing. Anything. A part of the level geometry, an interactable object, a pickup or an NPC.
Entities are also the things that receive messages and the things that you place down in the level editor.
Most of your entities will probably be placed in WorldCells, which are the basic level and streaming units of your virtual world.
Re-usable parts of the entity logic are usually placed into EntityComponents and entities are then assembled out of them.
Key concepts
ID
Each entity gets its own unique ID number. You can assign an ID number to an entity, or the framework can generate one for you. No two entities can have the same ID number, since then the framework will assume that one of the entitie is a copy and will yeet it.
Name
Entities can be given names, but unlike an ID, these are optional. This is also how you will refer to specific entities most of the time.
Type
Each entity has a type. It determines its behavior and what kinds of properties it has.
Properties
Each entity has properties. These can be numbers, strings, vectors or other kinds of types. An entity's properties can be edited in the level editor.
They are also called parameters, fields and entity data. Mostly because I keep forgetting how this concept is called.
Location/Rotation
Each entity gets a rotation and a location. This transform is used to determine in which WorldCell the entity is located in and when to load and unload it
Loading/Unloading
When an entity is constructed, either through code or from a record in a WorldCell file on disk, it starts out unloaded and has no EntityComponents attached to it. It just sits there, doing nothing.
When an entity is loaded, either when its WorldCell is loaded or on some other event, it will construct its EntityComponents and pass its properties to them.
When unloaded again, it will pack up and yeet all of its EntityComponents. This saves on computational resources – it allows the framework to process only a small part of all of the entities at the same time.
Programming in C++
#include <framework/entity.h>
API documentation
page.
If you want to create your own entity type, a good place to start would be by copying the Marker entity.
The other way would be to create a subclass of the Entity class and then implement all of its virtual methods. If you want the Entity to be loadable from a level file, you also need to add an entity type registration static method. Additionally, you could add the type to your project's entity definition file, so that the level editor and other utilities can process your entity type.
To interact with an entity, you first need to get a pointer to it. You can
get the pointer by using the Find() static method, which can
find an entity either by its ID number, or by its name.
Entity* entity1 = Entity::Find("bingus");
Entity* entity2 = Entity::Find(42069);
if (!entity1) {
printf("Entity bingus doesn't exist!");
}
It is also possible to query its transform and to change it.
vec3 position = entity->GetLocation();
quat rotation = entity->GetRotation();
position += vec3(0.0f, 1.0f, 0.0f);
entity->SetLocation(position);
There are a lot of other methods for the Entity class. Check the API documentation for them.
Scripting in Lua
The Lua API is basically the same as the C++ API.
local bingus = tram.entity.Find("bingus")
if bingus == nil then
print("Entity bingus doesn't exist!")
end
local position = bingus:GetLocation()
local rotation = bingus:GetRotation()
position = position + tram.math.vec3(0.0, 1.0, 0.0)
bingus:SetLocation(position)
