Apecs.Effectful

Adaptation of the apecs library for the effectful ecosystem.

Effectful Adaptation

data ECS (w :: Type) :: Effect

Provide the ability to query and manipulate worlds of type w.

Instances

type DispatchOf (ECS w)

Defined in Apecs.Effectful

type DispatchOf (ECS w) = 'Static 'WithSideEffects

newtype StaticRep (ECS w)

Defined in Apecs.Effectful

newtype StaticRep (ECS w) = ECS w

runECS :: IOE :> es => IO w -> Eff (ECS w ': es) a -> Eff es a

Run the ECS effect using the world initialization function provided by makeWorld or makeWorldAndComponents.

runGC :: forall w es. ECS w :> es => Eff es ()

Explicitly invoke the garbage collector.

type Get w c = Get w IO c

Indicates that world w has readable components of type c.

type Set w c = Set w IO c

Indicates that world w has writeable components of type c.

type Destroy w c = Destroy w IO c

Indicates that world w has deletable components of type c.

type Members w c = Members w IO c

Indicates that world w contains components of type c.

newEntity :: forall w c es. (ECS w :> es, Set w c, Get w EntityCounter) => c -> Eff es Entity

Writes the given components to a new entity.

newEntity_ :: forall w c es. (ECS w :> es, Set w c, Get w EntityCounter) => c -> Eff es ()

Writes the given components to a new entity.

get :: forall w c es. (ECS w :> es, Get w c) => Entity -> Eff es c

Read a component from an entity.

tryGet :: forall w c es. (ECS w :> es, Get w c) => Entity -> Eff es (Maybe c)

Read a component from an entity, if available.

set :: forall w c es. (ECS w :> es, Set w c) => Entity -> c -> Eff es ()

Writes a component to a given entity.

($=) :: forall w c es. (ECS w :> es, Set w c) => Entity -> c -> Eff es () infixr 2

Writes a component to a given entity.

destroy :: forall c w es. (ECS w :> es, Destroy w c) => Entity -> Eff es ()

Destroys component c for the given entity.

exists :: forall c w es. (ECS w :> es, Get w c) => Entity -> Eff es Bool

Returns whether the given entity has component c.

modify :: forall w cx cy es. (ECS w :> es, Get w cx, Set w cy) => Entity -> (cx -> cy) -> Eff es ()

Read a component and writes a new component of an entity.

($~) :: forall w cx cy es. (ECS w :> es, Get w cx, Set w cy) => Entity -> (cx -> cy) -> Eff es () infixr 2

Read the component cx and writes the component cy of an entity.

cmap :: forall w cx cy es. (ECS w :> es, Get w cx, Members w cx, Set w cy) => (cx -> cy) -> Eff es ()

Read the component cx and writes the component cy of all entities.

cmapM :: forall w cx cy es. (ECS w :> es, Get w cx, Set w cy, Members w cx) => (cx -> Eff es cy) -> Eff es ()

Monadic variant of cmap.

cmapM_ :: forall w c es. (ECS w :> es, Get w c, Members w c) => (c -> Eff es ()) -> Eff es ()

Monadic variant of cmap, ignoring the result of the applied function.

cfold :: forall w c a es. (ECS w :> es, Members w c, Get w c) => (a -> c -> a) -> a -> Eff es a

Fold over the components c of the game world.

cfoldM :: forall w c a es. (ECS w :> es, Members w c, Get w c) => (a -> c -> Eff es a) -> a -> Eff es a

Monadic variant of cfold.

cfoldM_ :: forall w c a es. (ECS w :> es, Members w c, Get w c) => (a -> c -> Eff es a) -> a -> Eff es ()

Monadic variant of cfold, ignoring the result.

Re-exports

newtype Entity

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.

Constructors

Entity

Fields

• unEntity :: Int

Instances

Enum Entity

Defined in Apecs.Core

Methods

succ :: Entity -> Entity

pred :: Entity -> Entity

toEnum :: Int -> Entity

fromEnum :: Entity -> Int

enumFrom :: Entity -> [Entity]

enumFromThen :: Entity -> Entity -> [Entity]

enumFromTo :: Entity -> Entity -> [Entity]

enumFromThenTo :: Entity -> Entity -> Entity -> [Entity]

Num Entity

Defined in Apecs.Core

Methods

(+) :: Entity -> Entity -> Entity

(-) :: Entity -> Entity -> Entity

(*) :: Entity -> Entity -> Entity

negate :: Entity -> Entity

abs :: Entity -> Entity

signum :: Entity -> Entity

fromInteger :: Integer -> Entity

Show Entity

Defined in Apecs.Core

Methods

showsPrec :: Int -> Entity -> ShowS

show :: Entity -> String

showList :: [Entity] -> ShowS

Eq Entity

Defined in Apecs.Core

Methods

(==) :: Entity -> Entity -> Bool

(/=) :: Entity -> Entity -> Bool

Ord Entity

Defined in Apecs.Core

Methods

compare :: Entity -> Entity -> Ordering

(<) :: Entity -> Entity -> Bool

(<=) :: Entity -> Entity -> Bool

(>) :: Entity -> Entity -> Bool

(>=) :: Entity -> Entity -> Bool

max :: Entity -> Entity -> Entity

min :: Entity -> Entity -> Entity

type Storage Entity

Defined in Apecs.Components

type Storage Entity = EntityStore

data EntityCounter

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

Instances

Component EntityCounter

Defined in Apecs.Util

Associated Types

type Storage EntityCounter

Monoid EntityCounter

Defined in Apecs.Util

Methods

mempty :: EntityCounter

mappend :: EntityCounter -> EntityCounter -> EntityCounter

mconcat :: [EntityCounter] -> EntityCounter

Semigroup EntityCounter

Defined in Apecs.Util

Methods

(<>) :: EntityCounter -> EntityCounter -> EntityCounter

sconcat :: NonEmpty EntityCounter -> EntityCounter

stimes :: Integral b => b -> EntityCounter -> EntityCounter

Show EntityCounter

Defined in Apecs.Util

Methods

showsPrec :: Int -> EntityCounter -> ShowS

show :: EntityCounter -> String

showList :: [EntityCounter] -> ShowS

Eq EntityCounter

Defined in Apecs.Util

Methods

(==) :: EntityCounter -> EntityCounter -> Bool

(/=) :: EntityCounter -> EntityCounter -> Bool

type Storage EntityCounter

Defined in Apecs.Util

type Storage EntityCounter = ReadOnly (Global EntityCounter)

data Not a

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.

Constructors

Not

Instances

Has w m c => Has w m (Not c)

Defined in Apecs.Components

Methods

getStore :: SystemT w m (Storage (Not c))

Component c => Component (Not c)

Defined in Apecs.Components

Associated Types

type Storage (Not c)

type Storage (Not c)

Defined in Apecs.Components

type Storage (Not c) = NotStore (Storage c)

class Elem (Storage c) ~ c => Component c

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

Associated Types

type Storage c

Instances

Component EntityCounter

Defined in Apecs.Util

Associated Types

type Storage EntityCounter

Component c => Component (Filter c)

Defined in Apecs.Components

Associated Types

type Storage (Filter c)

Component c => Component (Not c)

Defined in Apecs.Components

Associated Types

type Storage (Not c)

class (Monad m, Component c) => Has w (m :: Type -> Type) c where

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

Methods

getStore :: SystemT w m (Storage c)

Instances

Has w m c => Has w m (Filter c)

Defined in Apecs.Components

Methods

getStore :: SystemT w m (Storage (Filter c))

Has w m c => Has w m (Not c)

Defined in Apecs.Components

Methods

getStore :: SystemT w m (Storage (Not c))

data Cache (n :: Nat) s

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.

Instances

(MonadIO m, ExplDestroy m s) => ExplDestroy m (Cache n s)

Defined in Apecs.Stores

Methods

explDestroy :: Cache n s -> Int -> m ()

(MonadIO m, ExplGet m s) => ExplGet m (Cache n s)

Defined in Apecs.Stores

Methods

explGet :: Cache n s -> Int -> m (Elem (Cache n s))

explExists :: Cache n s -> Int -> m Bool

(MonadIO m, ExplInit m s, KnownNat n, Cachable s) => ExplInit m (Cache n s)

Defined in Apecs.Stores

Methods

explInit :: m (Cache n s)

(MonadIO m, ExplMembers m s) => ExplMembers m (Cache n s)

Defined in Apecs.Stores

Methods

explMembers :: Cache n s -> m (Vector Int)

(MonadIO m, ExplSet m s) => ExplSet m (Cache n s)

Defined in Apecs.Stores

Methods

explSet :: Cache n s -> Int -> Elem (Cache n s) -> m ()

(KnownNat n, Cachable s) => Cachable (Cache n s)

Defined in Apecs.Stores

type Elem (Cache n s)

Defined in Apecs.Stores

type Elem (Cache n s) = Elem s

data Global c

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.

Instances

MonadIO m => ExplGet m (Global c)

Defined in Apecs.Stores

Methods

explGet :: Global c -> Int -> m (Elem (Global c))

explExists :: Global c -> Int -> m Bool

(Monoid c, MonadIO m) => ExplInit m (Global c)

Defined in Apecs.Stores

Methods

explInit :: m (Global c)

MonadIO m => ExplSet m (Global c)

Defined in Apecs.Stores

Methods

explSet :: Global c -> Int -> Elem (Global c) -> m ()

type Elem (Global c)

Defined in Apecs.Stores

type Elem (Global c) = c

data Map c

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

Instances

MonadIO m => ExplDestroy m (Map c)

Defined in Apecs.Stores

Methods

explDestroy :: Map c -> Int -> m ()

(MonadIO m, Typeable c) => ExplGet m (Map c)

Defined in Apecs.Stores

Methods

explGet :: Map c -> Int -> m (Elem (Map c))

explExists :: Map c -> Int -> m Bool

MonadIO m => ExplInit m (Map c)

Defined in Apecs.Stores

Methods

explInit :: m (Map c)

MonadIO m => ExplMembers m (Map c)

Defined in Apecs.Stores

Methods

explMembers :: Map c -> m (Vector Int)

MonadIO m => ExplSet m (Map c)

Defined in Apecs.Stores

Methods

explSet :: Map c -> Int -> Elem (Map c) -> m ()

Cachable (Map s)

Defined in Apecs.Stores

type Elem (Map c)

Defined in Apecs.Stores

type Elem (Map c) = c

data Unique c

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.

Instances

MonadIO m => ExplDestroy m (Unique c)

Defined in Apecs.Stores

Methods

explDestroy :: Unique c -> Int -> m ()

(MonadIO m, Typeable c) => ExplGet m (Unique c)

Defined in Apecs.Stores

Methods

explGet :: Unique c -> Int -> m (Elem (Unique c))

explExists :: Unique c -> Int -> m Bool

MonadIO m => ExplInit m (Unique c)

Defined in Apecs.Stores

Methods

explInit :: m (Unique c)

MonadIO m => ExplMembers m (Unique c)

Defined in Apecs.Stores

Methods

explMembers :: Unique c -> m (Vector Int)

MonadIO m => ExplSet m (Unique c)

Defined in Apecs.Stores

Methods

explSet :: Unique c -> Int -> Elem (Unique c) -> m ()

type Elem (Unique c)

Defined in Apecs.Stores

type Elem (Unique c) = c

newtype SystemT w (m :: Type -> Type) a

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.

Constructors

SystemT (ReaderT w m a)

Instances

Monad m => MonadReader w (SystemT w m)

Defined in Apecs.Core

Methods

ask :: SystemT w m w

local :: (w -> w) -> SystemT w m a -> SystemT w m a

reader :: (w -> a) -> SystemT w m a

MonadTrans (SystemT w)

Defined in Apecs.Core

Methods

lift :: Monad m => m a -> SystemT w m a

MonadIO m => MonadIO (SystemT w m)

Defined in Apecs.Core

Methods

liftIO :: IO a -> SystemT w m a

Applicative m => Applicative (SystemT w m)

Defined in Apecs.Core

Methods

pure :: a -> SystemT w m a

(<*>) :: SystemT w m (a -> b) -> SystemT w m a -> SystemT w m b

liftA2 :: (a -> b -> c) -> SystemT w m a -> SystemT w m b -> SystemT w m c

(*>) :: SystemT w m a -> SystemT w m b -> SystemT w m b

(<*) :: SystemT w m a -> SystemT w m b -> SystemT w m a

Functor m => Functor (SystemT w m)

Defined in Apecs.Core

Methods

fmap :: (a -> b) -> SystemT w m a -> SystemT w m b

(<$) :: a -> SystemT w m b -> SystemT w m a

Monad m => Monad (SystemT w m)

Defined in Apecs.Core

Methods

(>>=) :: SystemT w m a -> (a -> SystemT w m b) -> SystemT w m b

(>>) :: SystemT w m a -> SystemT w m b -> SystemT w m b

return :: a -> SystemT w m a

MonadCatch m => MonadCatch (SystemT w m)

Defined in Apecs.Core

Methods

catch :: Exception e => SystemT w m a -> (e -> SystemT w m a) -> SystemT w m a

MonadMask m => MonadMask (SystemT w m)

Defined in Apecs.Core

Methods

mask :: ((forall a. SystemT w m a -> SystemT w m a) -> SystemT w m b) -> SystemT w m b

uninterruptibleMask :: ((forall a. SystemT w m a -> SystemT w m a) -> SystemT w m b) -> SystemT w m b

generalBracket :: SystemT w m a -> (a -> ExitCase b -> SystemT w m c) -> (a -> SystemT w m b) -> SystemT w m (b, c)

MonadThrow m => MonadThrow (SystemT w m)

Defined in Apecs.Core

Methods

throwM :: Exception e => e -> SystemT w m a

makeWorld :: String -> [Name] -> Q [Dec]

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

makeWorldAndComponents :: String -> [Name] -> Q [Dec]

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

global :: Entity

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

explInit :: ExplInit m s => m s

Initialize a new empty store.

asks

Arguments

:: MonadReader r m

=> (r -> a)

The selector function to apply to the environment.

-> m a

Retrieves a function of the current environment.