State

NOTE Until our documentation settles down, USAGE.md is a better source of up to date information

This part of Arcadia is under active development. We're documenting the parts that are most settled, but expect changes.

Unity components implement both behavior and state. State manifests as mutable fields on component instances that the component (or other components) are expected to read from and write to. Arcadia hooks are just functions, so they do not normally maintain state. Instead, a seperate Arcadia state component and related API are provided. This is still mutable state, but we hope to imbue this part of the engine with a little more composability and concurrency.

The idea is to give every GameObject that uses Arcadia state a single persistent hashmap inside an atom. Code can read the whole map, or update a single key at a time (merging into the hashmap has also been suggested). If different libraries use namespace qualified keywords, then multiple codebases can write interact with the same single state atom without colliding or coordinating. Wrapping the hashmap in an atom means that updating Arcadia state is threadsafe and can be done safely from arbitrary Clojure code.

State is set with set-state!, remove-state!, and update-state! and read with state

(def cube (create-primitive :cube))

(set-state! cube :friendly? true)
(set-state! cube :health 100.0)

(state cube) ;; {:friendly? true, :health 100.0}
(state cube :friendly?) ;; true

(remove-state! cube :friendly?)
(state cube) ;; {:health 100.0}
(state cube :friendly?) ;; nil

(update-state! cube :health inc)
(state cube :health) ;; 101.0