Apecs

A SystemT is a newtype around `ReaderT w m a`, where w is the game world variable. Systems serve to

• Allow type-based lookup of a component's store through getStore.

• Lift side effects into their host Monad.

A component is defined by specifying how it is stored. The constraint ensures that stores and components are mapped one-to-one.

An Entity is just an integer, used to index into a component store. In general, use newEntity, cmap, and component tags instead of manipulating these directly.

For performance reasons, negative values like (-1) are reserved for stores to represent special values, so avoid using these.

Has w m c means that world w can produce a Storage c. It is parameterized over m to allow stores to be foreign.

Pseudocomponent indicating the absence of a. Mainly used as e.g. cmap $ (a, Not b) -> c to iterate over entities with an a but no b. Can also be used to delete components, like cmap $ a -> (Not :: Not a) to delete every a component.

A map based on Data.IntMap.Strict. O(log(n)) for most operations.

A Unique contains zero or one component. Writing to it overwrites both the previous component and its owner. Its main purpose is to be a Map optimized for when only ever one component inhabits it.

A Global contains exactly one component. The initial value is mempty from the component's Monoid instance. Querying a Global at any Entity yields this one component, effectively sharing the component between all entities.

A Global component can be read with get 0 or get 1 or even get undefined. The convenience entity global is defined as -1, and can be used to make operations on a global more explicit, i.e. 'Time t <- get global'.

You also can read and write Globals during a cmap over other components.

A cache for arbitrary types, using a boxed vector, adding an extra indirection for each component.

A cache for storable types, using a storable vector, storing components directly in the cache.

A cache for unboxed types, using an unboxed vector, storing components directly in the cache.

A cache around another store. Caches store their members in a fixed-size vector, so read/write operations become O(1). Caches can provide huge performance boosts, especially when working with large numbers of components.

The cache size is given as a type-level argument.

Note that iterating over a cache is linear in cache size, so sparsely populated caches might decrease performance. In general, the exact size of the cache does not matter as long as it reasonably approximates the number of components present.

The cache uses entity (-2) internally to represent missing entities. If you manually manipulate Entity values, be careful that you do not use (-2)

The actual cache is not necessarily the given argument, but the next biggest power of two. This is allows most operations to be expressed as bit masks, for a large potential performance boost.

Initialize a new empty store.

Read a Component

Writes a Component to a given Entity. Will overwrite existing Components.

Writes a Component to a given Entity. Will overwrite existing Components.

set operator

Destroys component c for the given entity.

Returns whether the given entity has component c

Applies a function, if possible.

Applies a function, if possible.

modify operator

Maps a function over all entities with a cx, and writes their cy.

Conditional cmap, that first tests whether the argument satisfies some property. The entity needs to have both a cx and cp component.

Monadically iterates over all entites with a cx, and writes their cy.

Monadically iterates over all entites with a cx

Fold over the game world; for example, cfold max (minBound :: Foo) will find the maximum value of Foo. Strict in the accumulator.

Monadically fold over the game world. Strict in the accumulator.

Monadically fold over the game world. Strict in the accumulator.

Collect matching components into a list by using the specified test/process function. You can use this to preprocess data before returning. And you can do a test here that depends on data from multiple components. Pass Just to simply collect all the items.

Run a system in a game world

Run a system in a game world

Explicitly invoke the garbage collector

Component used by newEntity to track the number of issued entities. Automatically added to any world created with makeWorld

Writes the given components to a new entity, and yields that entity. The return value is often ignored.

Writes the given components to a new entity without yelding the result. Used mostly for convenience.

Convenience entity, for use in places where the entity value does not matter, i.e. a global store.

The typical way to create a world record, associated Has instances, and initialization function.

makeWorld "MyWorld" [''Component1, ''Component2, ...]

turns into

data MyWorld = MyWorld Component1 Component2 ... EntityCounter
instance MyWorld `Has` Component1 where ...
instance MyWorld `Has` Component2 where ...
...
instance MyWorld `Has` EntityCounter where ...

initMyWorld :: IO MyWorld
initMyWorld = MyWorld <$> initStore <*> initStore <*> ... <*> initStore

Calls makeWorld and makeMapComponents, i.e. makes a world and also defines Component instances with a Map store.

Retrieve a function of the current environment.

• asks f = liftM f ask

Fetch the value of the environment.

Lift a computation from the IO monad. This allows us to run IO computations in any monadic stack, so long as it supports these kinds of operations (i.e. IO is the base monad for the stack).

Example

import Control.Monad.Trans.State -- from the "transformers" library

printState :: Show s => StateT s IO ()
printState = do
  state <- get
  liftIO $ print state

Had we omitted liftIO, we would have ended up with this error:

• Couldn't match type ‘IO’ with ‘StateT s IO’
 Expected type: StateT s IO ()
   Actual type: IO ()

The important part here is the mismatch between StateT s IO () and IO ().

Luckily, we know of a function that takes an IO a and returns an (m a): liftIO, enabling us to run the program and see the expected results:

> evalStateT printState "hello"
"hello"

> evalStateT printState 3
3

Lift a computation from the argument monad to the constructed monad.

Proxy is a type that holds no data, but has a phantom parameter of arbitrary type (or even kind). Its use is to provide type information, even though there is no value available of that type (or it may be too costly to create one).

Historically, Proxy :: Proxy a is a safer alternative to the undefined :: a idiom.

>>> Proxy :: Proxy (Void, Int -> Int)Proxy

Proxy can even hold types of higher kinds,

>>> Proxy :: Proxy EitherProxy

>>> Proxy :: Proxy FunctorProxy

>>> Proxy :: Proxy complicatedStructureProxy