Updated for v0.3.3

Entity: usage on the serverside

An entity is an object that has id, x, and y properties. An entity has a persistent existence, meaning it can stick around for numerous ticks of a game loop.

There's no actual entity class or object to inherit from or create via nengi. This is part of nengi trying to stay out of game code, and allow the game developer as much freedom as possible.

To make an entity that is compatible with nengi, do the following:


class ExampleEntity {
    constructor() {
        this.id = -1
        this.x = 0
        this.y = 0
ExampleEntity.protocol = {
    x: nengi.Number,
    y: nengi.Number

This is the most basic concept of an entity that will work with nengi. After creating this definition, be sure to add it to the nengiConfig protocols.

in nengiConfig's protocol seciton:

    entities: [
        ['ExampleEntity', require('./path/to/ExampleEntity')]

The entity can now be added to an instance and it will be automatically sent across the network to clients who can see the entity.

For additional information see the manual page on client.view

usage with an Instance

var instance = new nengi.Instance(nengiConfig)
var entity = new ExampleEntity()

MUTATION: addEntity will assign an id, type, and protocol to the entity. Becareful not to overwrite these with your own variables or vice versa.

An entity will stay in an instance forever unless explicitly removed. In a real game perhaps you maintain an array of all your entities, and at some point you decide that it is time to remove an entity (maybe its hitpoints dropped to 0?). Here's how removing the entity would look:


MUTATION: removeEntity will set the id to -1. If you need to use the id for something (for example removing the entity from other areas in your logic, such as a leaderboard) be sure to do so before invoking instance.removeEntity(entity).

Entity: usage on the clientside

Entity data received on the client comes in 3 flavors (create, update, delete).

// reading an entitySnapshot on the client
network.entities.forEach(snapshot => {
    snapshot.createEntities.forEach(entity => {
        console.log('create', entity)
        // create { id: 65534, type: 0, x: 55, y: 68, protocol: { name: 'ExampleEntity', ... }} 

    snapshot.updateEntities.forEach(update => {
        console.log('update', update)
        // update { id: 65533, prop: 'x', value: 63, path: ['x'] }

    snapshot.deleteEntities.forEach(id => {
        console.log('delete', id)
        // delete 65532

What do we do with all this?

entity - create

Denotes that the client has just encountered an entity. Perhaps the entity just spawned into the game world, or maybe it simply moved to within this client's view.

{ id: 65534, type: 0, x: 55, y: 68, protocol: { name: 'ExampleEntity', ... }}

TODO: Create a clientside representation of the entity and copy the networked properties (id, type, x, y, etc.) to it. Be sure to save the entity in such a manner that we can look it up by its id so that we can update its state in the future.

entity - update

Denotes that an entity within view of this client has experienced a change. This could be any property defined in the protocol.

{ id: 65533, prop: 'x', value: 63, path: ['x'] }

TODO: Look up entity 65533 by its id and then change its x to 63.

entity - delete

Denotes that an entity is no longer visible to this client.


TODO: Look up entity 65522 by its id delete it, and remove it from any renderer if needed.