nengi.Entity

Updated for v1.0.0

Entity: usage on the serverside

Entities are objects whose state should be automatically synchronized with any client that can see the entity

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:

• create a class that has the properties nid, x, y
• add a protocol to the class that includes x, y, (and whatever else!)

All entities in 1.0.0 must have x, y! A future version of nengi likely remove this requirement.

ExampleEntity

class ExampleEntity {
    constructor() {
        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', ExampleEntity] // class
    ],

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

const instance = new nengi.Instance(nengiConfig)
const entity = new ExampleEntity()
instance.addEntity(entity)

MUTATION: addEntity will assign an nid, ntype, and protocol to the entity. Be sure not have a conflict with nengi.

instance.removeEntity(entity)

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 { nid: 65534, ntype: 0, x: 55, y: 68, protocol: { name: 'ExampleEntity', ... }} 
    })

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

    snapshot.deleteEntities.forEach(nid => {
        console.log('delete', nid)
        // 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.

65522

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