Game Entities, Blueprints & Scripting

Wikis > Game engine manual > Game Entities, Blueprints & Scripting

Game entities are objects you place in the level that contain special game properties. Examples include characters with the functionality to get input from the user to move in the level, trigger boxes to detect when entities enter and leave a certain volume, and post effect bubbles that can create localized post effects. Game entities are created out of Blueprints, which in turn consist of a collection of Properties with various functions. These include the ability to receive player input, to be affected by physics, or to have scripting functionality.

Scripting in Nebula is done through Lua scripts attached to certain entities, which trigger when that entity encounter/meets a particular condition: such as being collided with by another entity. With scripts, you can create custom events. For instance, when the Player-entity collides with the DeathTrap-entity, the Player-entity should die (and play the death animation).

While the set of exposed Lua scripting functions and the creation of new Blueprint Properties is in the realm of game developers/programmers, it is easy enough to pick up the basics of Lua or create a new Blueprint out of pre-existing Properties.


Blueprints are containers for Properties. Properties can be very advanced, and more can be created depending on the game’s need, but there are a handful of basic properties that are default in Nebula. These include having a graphics model, receiving input from a player, calculating physics, receiving scripts, and so on. By attaching different Properties to a Blueprint, and then placing a Game Entity based on that Blueprint, you can create objects with custom game functionality in your level. You can then edit the settings of the Game Entity’s properties in the Level Editor, for instance attaching scripts to the script property.

While you can modify settings in the Level Editor, you can also create Templates (presets) for Blueprints. For instance, you can place a default AnimatedPhysics/Triggerbox Game Entity into your level, rename it, give it a new graphics mesh, and so on. However, if you need to place very many of these customized versions, or if you need to be able to spawn them in-game, you need to create a new Template.

Blueprints are stored as .xml files in /projectdirectory/data/tables/db/

You can create a new Template simply by copying one of the existing lines (starting with “<Item…” and replacing the necessary strings to suit your needs.


Common Game Entities

AnimatedPhysics – Physics are further discussed in the Physics section of the manual. This Blueprint allows models with joint-animated physics, which is necessary for things like doors sliding open (with an animation based on joints).

Camera – Place this into the level and you can play through the level as a flying camera.

Player – This is a full player character, allowing you to insert a character mesh, define certain preset animations (walk, idle, death, etc).

PostEffectBubble – Lets you place local post effects that override global settings within their volume.

Trigger – Place trigger volumes to enhance your scripting by detecting when entities enter or leave the trigger volumes.


Creating new blueprints

You can create new blueprints from within the Level Editor’s Game menu. Opening up the Blueprints… window shows the following:


To create new Blueprints, click the New button and it opens up the Category Editor. This editor allows to create your own Blueprints with the available properties which exist in the list. Simply use the interface to attach properties, set a name, and hit OK. You’ll then be able to place it from the Game Entities menu.



For further information, see the Blueprint Properties Reference.




In the Level Editor, you can attach scripts to Game Entities with the Scripting property. Scripts can do all sorts of things: make certain things happen upon player input, for instance, or when two objects collide, or an entity enters a Trigger Volume. You can kill the player, play animations, spawn new entities, and so on. Scripts are written with a set of exposed commands in the Lua scripting language. See Lua’s website for details on the (simple) syntax, and see the Scripting Reference for a full list of all available commands.

A simple example of a script that could be attached to a Trigger Volume, which makes the player model play a WaveAnimation when the player is inside the volume and presses down the Y key:

function oninside(eid, othereid)
if getcategory(othereid) == “Player” then
if == keypressed(“Y”) then
playanimclip(othereid, “WaveAnimation”, 1, false)

oninside – a function specific to trigger volumes, which runs for every frame another entity (othereid) is inside the trigger volume (eid – self or “Entity ID”) with the script. getcategory returns the (Blueprint?) category of othereid, the entity which entered the triggering volume. The “1,false)” portion of the playanimclip command defines how many times the clip should be played (1 time) and whether it should play immediately, or wait for other animations currently playing to finish (false).



How to create a script

You can create new scripts from the Level Editor’s Game menu. You don’t need to do much when you first create it, simply name it. It will then be stored as a .lua file under /projectdirectory/data/scripts/

You can then browse to and attach the script file to the Scripting Property of a Game Entity placed in the Level Editor. If your entity doesn’t have a Scripting Property, you can edit its Blueprint to have that property, or create a new Blueprint altogether.


Once attached, you can edit the script with the button next to the browse icon. Simply open it, write your code, hit Save (or CTRL+S) and try playing the level. If something is wrong, you’ll usually get a fairly descriptive error message.



Useful commands:

Some of the more useful functions exposed for use are:



oninit(eid) runs once when object is created

onframe(eid) runs every frame

oncollision(eid, othereid, point, normal)  runs when colliding (needs to have collision feedback enabled on the entities’ physics property)

oninput(eid) runs on inputfocus and when you press any key


onenter(eid,othereid) runs when entering trigger

oninside(eid,othereid) runs every frame inside object

onexit(eid,othereid)  runs when exiting trigger




Retrieves an entity unique id for use in scripts
uint EntityID = getentitybyname(string Name)


Play animation clip
playanimclip(uint ___entityId, string Clip, float LoopCount, bool Queue)


Player dies
playerdeath(uint ___entityId)


See Scripting Reference for all commands as well as examples.

Skip to toolbar