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 byinit_state/2
and modified by the System callbacks and functionsinstance_key
is the key to identify the Instance which spawns the system, it can be used to reach its other systemsmap_key
is the key to identify the map on which the puppets have been spawnedpuppets
is aMapSet
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
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.
The inner state of the Server process.
Link to this section Functions
A macro to ease the definition of a new System which provides the cast keyword.
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
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.
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.
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.