Updated for v1.0.0

A LocalMessage consists of x, y, and zero or more properties and values to be sent to a client. Unliked the regular nengi.Message, nengi.LocalMessage is automatically sent to clients who can "see" the location at which the message was created.

LocalMessages are great for sending data that only needs to be sent to those players in the immediate vicinity. Casting a quick spell, firing a gun, show an impact effect, playing a sound, are all things that might be worth networking via LocalMessages.

A future version of nengi will likely do away with the formal category of "localMessages" and instead have a way of sending regular messages only to players in an area (same thing in the end, just no need for a different definition).


class ExampleLocalMessage {
    constructor(x, y) {
        this.x = x
        this.y = y
        this.baz = true
ExampleLocalMessage.protocol = {
    x: nengi.Number,
    y: nengi.Number
    baz: nengi.Boolean

After creating this definition, be sure to add it to the nengiConfig protocols.


    localMessages: [
        ['ExampleLocalMessage', ExampleLocalMessage]

usage with an Instance

instance.addLocalMessage(new ExampleLocalMessage(56, 87))

This localMessage will then be automatically sent to any client whose view would contain the message. In this specific example that would be any clients who can see [56, 87].


// reading localMessages
network.localMessages.forEach(localMEssage => {
    // { ntype: 0, x: 56, y: 57, baz: true, protocol: { name: 'ExampleLocalMessage', ... }}

LocalMessage (random advanced stuff)

LocalMessage without x & y on the protocol:

A localMessage must have an x and y for it to be added to the instance. This x and y are the spatial data needed to determine if the localMessages falls within a client's view. However, just because a localMessage has an x and y does not mean that x and y have to be on the protocol. An example of a feature that could use this technique meaningfully would be something like this BloodEffect:

class Blood {
    constructor(victim) {
        this.x = victim.x
        this.y = victim.y
        this.entityId = victim.nid
Blood.protocol = {
    entityId: nengi.UInt32
// then...
instance.addLocalMessage(new Blood(someEntity))

The result of this would be that players near `someEntity` (the victim) would receive the Blood localMessage. This localMessage does not contain an x,y saying where it occured on the screen -- but it does contain an entityId, which is hypothetically enough data that the game client would know where to display the blood (e.g. show the blood coming from the specified entity).