lkn-core v0.3.0 Lkn.Core.System behaviour View Source

A behaviour module for implementing and querying a System.

Note: You are not supposed to spawn a System yourself. The Lkn.Core.Instance takes care of that for you. This is why you will not find any start* function here.

The core of this module is the defsystem/2 macro. It is the recommended way to implement of System, that is a Process that handles one aspect of the gameplay. Before we going any further, lets have a look at a following minimal example.

defsystem Sys do
  # 1. Specify which 'Component's are required by this 'System'.
  @map Sys.MapSpec
  @puppet Sys.PuppetSpec

  # 2. Implementation of the 'System' callbacks.
  def init_state(_instance_key, _map_key) do
    # return some state
  end

  def puppet_enter(state, _instance_key, _map_key, _puppets, _puppet_key)
    # we do nothing, but we could
    state
  end

  def puppet_leave(state, _instance_key, _map_key, _puppets, _puppet_key)
    # we do nothing, but we could
    state
  end

  # 3. Define some specific functions
  cast func1(a :: integer, b :: boolean) do
    # here you can use 'a' and 'b', but also 'state',
    # 'puppets', 'map_key' and 'instance_key'

    # you have to return the new state value
    state
  end
end

Map and Puppet Components

A System handles one facet of the gameplay. Its purpose is to manipulate the set of “compatible” of Puppets. A System is tied to two Component Specification Modules (that is two modules defined with the Lkn.Core.Component.defcomponent/2 macro). A Component is a Proxy to manipulate an Entity. It abstracts away its underlying structure and expose a common interface. See Lkn.Core.Component to learn how to specify then implement a Component.

To define which Component is required for a Map and which one is required for a Puppet, we use the @map and @puppet annotations.

The System Behaviour

The System callbacks can be divided into two categories. The init_map/2 function is called only one time to initialize the inner state of the System. This state implementation is at the discretion of the developer. The other callbacks are a set of hooks which are called when a particular event occures.

The cast Keyword

In addition to the System callbacks which are shared by all the Systems, each System exposes a public interface the Puppeteer can use to actually play. The function interface are defined using the cast keyword.

You can use the cast keyword as follows: cast <func_name>([arg_name :: arg_type]*) do <block> end. Inside the block, you can use the arguments you have defined. In addition, you also can use the following variables:

  • state is the current state of the System, as initialized by init_state/2 and modified by the System callbacks and functions
  • instance_key is the key to identify the Instance which spawns the system, it can be used to reach its other systems
  • map_key is the key to identify the map on which the puppets have been spawned
  • puppets is a MapSet of all the Puppets currently in the Instance and “compatible” with the System

In addition to this variables, you also can use the notify/1 function. It takes a lambda of types (Lkn.Core.Puppeteer.k -> any). It can be used to reach all the Puppeteers that have populated the Instance with their Puppets.

The block has to return the new system state.

The defsystem will generate a client function to use this function. In addition to the specified arguments, it takes an additional one: an Instance key.

Link to this section Summary

Types

m()

A System defined using the defsystem/2 macro

A set of “compatible” puppets

The inner state of the Server process

Functions

A macro to ease the definition of a new System which provides the cast keyword

Returns the number of “compatible” Puppets of a given System registered to a given Instance

Callbacks

Initialize the state of the system

A hook function which is called when a “compatible” puppet enters the Instance

A hook function which is called when a “compatible” puppet leaves the Instance

Link to this section Types

A System defined using the defsystem/2 macro.

A set of “compatible” puppets.

Link to this type state() View Source
state() :: any

The inner state of the Server process.

Link to this section Functions

Link to this macro defsystem(name, list) View Source (macro)

A macro to ease the definition of a new System which provides the cast keyword.

Link to this function population_size(instance_key, system) View Source
population_size(Lkn.Core.Instance.k, m) :: integer

Returns the number of “compatible” Puppets of a given System registered to a given Instance.

Link to this section Callbacks

Link to this callback init_state(instance_key, map_key) View Source
init_state(instance_key :: Lkn.Core.Instance.k, map_key :: Lkn.Core.Map.k) :: state

Initialize the state of the system.

With the instance_key, you can trigger other systems of the same instance. With the map_key, you can request through the Map Component some information about the map.

Link to this callback puppet_enter(state, instance_key, map_key, puppets, puppet_key) View Source
puppet_enter(state :: state, instance_key :: Lkn.Core.Instance.k, map_key :: Lkn.Core.Map.k, puppets :: Lkn.Core.System.puppets, puppet_key :: Lkn.Core.Puppet.k) :: state

A hook function which is called when a “compatible” puppet enters the Instance.

Link to this callback puppet_leave(state, instance_key, map_key, puppets, puppet_key) View Source
puppet_leave(state :: state, instance_key :: Lkn.Core.Instance.k, map_key :: Lkn.Core.Map.k, puppets :: Lkn.Core.System.puppets, puppet_key :: Lkn.Core.Puppet.k) :: state

A hook function which is called when a “compatible” puppet leaves the Instance.