-
Notifications
You must be signed in to change notification settings - Fork 108
arcadia.core (beta)
(log & args)
Log message to the Unity console. Arguments are combined into a string.
(null->nil x)
Same as identity, except if x is a null UnityEngine.Object,
will return nil.
More details and rationale are available in the wiki.
(null? x)
Should x be considered nil? (null? x) will evalute to true
if x is in fact nil, or if x is a UnityEngine.Object instance
such that (UnityEngine.Object/op_Equality x nil) returns true.
More details and rationale are available in the wiki.
(instantiate original)
(instantiate original position)
(instantiate original position rotation)
Clones the original object and returns the clone. The clone can
optionally be given a new position or rotation as well. Wraps
UnityEngine.Object/Instantiate.
(create-primitive prim)
(create-primitive prim name)
Creates a game object with a primitive mesh renderer and appropriate
collider. prim can be a PrimitiveType or one of :sphere :capsule
:cylinder :cube :plane :quad. Wraps UnityEngine.GameObject/CreatePrimitive.
(destroy obj)
(destroy obj t)
Removes a GameObject, component or asset. When called with t, the removal
happens after t seconds. Wraps UnityEngine.Object/Destroy.
(destroy-immediate obj)
Removes a GameObject, component or asset immediately.
Wraps UnityEngine.Object/DestroyImmediate.
(retire obj)
If in Play mode, calls Destroy, otherwise calls DestroyImmediate.
(object-typed t)
Returns one object of Type t. The object selected seems to be
the first object in the array returned by objects-typed.
Wraps UnityEngine.Object/FindObjectOfType.
(objects-typed t)
Returns an array of all active loaded objects of Type t. The order is consistent
but undefined. Wraps UnityEngine.Object/FindObjectsOfType.
(object-named name)
Returns one GameObject named name. Wraps UnityEngine.GameObject/Find.
(objects-named name)
Returns a sequence of all GameObjects named name. name can be a string or a regular expression.
(object-tagged t)
Returns one active GameObject tagged t. Tags are managed from the
Unity Tag Manager.
Wraps UnityEngine.GameObject/FindWithTag.
(objects-tagged t)
Returns an array of active GameObjects tagged tag. Returns empty
array if no GameObject was found. Tags are managed from the
Unity Tag Manager.
Wraps UnityEngine.GameObject/FindGameObjectsWithTag.
(gobj x)
Coerces x, expected to be a GameObject or Component, to a
corresponding live (non-destroyed) GameObject instance or to nil by
the following policy:
- If
xis a live GameObject, returns it. - If
xis a destroyed GameObject, returns nil. - If
xis a live Component instance, returns its containing GameObject. - If
xis a destroyed Component instance, returns nil. - If
xis nil, returnsnil. - Otherwise throws an ArgumentException.
(child+ x child)
(child+ x child world-position-stays)
Makes x the new parent of child. x and child can be GameObjects or
Components.
If world-position-stays is true then child retains its world position after
being reparented.
(child- x child)
(child- x child world-position-stays)
Removes x as the parent of child. x and child can be GameObjects or
Components.
The new parent of child becomes nil and it is moved to the top level of
the scene hierarchy.
If world-position-stays is true then child retains its world position after
being reparented.
(children x)
Gets the children of x as a persistent vector. x can be a GameObject or
a Component.
(cmpt x t)
Returns the first Component of type t attached to x. Returns nil if no
such component is attached. x can be a GameObject or Component.
(cmpts x t)
Returns all Components of type t attached to x
as a (possibly empty) array. x can be a GameObject or Component.
(cmpt+ x t)
Adds a new Component of type t from x. x can be a GameObject or
Component. Returns the new Component.
(cmpt- x t)
Removes every Component of type t from x. x can be a GameObject or
Component. Returns nil.
(ensure-cmpt x t)
If GameObject x has a component of type t, returns it. Otherwise, adds
a component of type t and returns the new instance.
with-gobj macro
(with-gobj [gob-name x] & body)
Bind the GameObject x to the name gob-name in body. If x is a
Component its attached GameObject is used.
with-cmpt macro
(with-cmpt gob bindings & body)
binding => name component-type
For each binding, looks up component-type on gob and binds it to name. If
Component does not exist, it is created and bound to name. Evalutes body
in the lexical context of all names.
if-cmpt macro
(if-cmpt gob [cmpt-name cmpt-type] then & else)
Execute body of code if gob has a component of type cmpt-type
(descendents x)
Returns a sequence of x's children. x can be a GameObject or a Component.
(available-hooks)
Returns a sorted seq of all permissible hook keywords.
(hook+ obj event-kw k f)
Attach a Clojure function to a Unity event on obj. The function f
will be invoked every time the event identified by event-kw is sent by Unity. f
must have the same arity as the expected Unity event. When called with a key k
this key can be passed to event-kw- to remove the function.
(hook- obj event-kw key)
Removes callback from GameObject obj on the Unity event
corresponding to event-kw at key, if it exists. Reverse of
(hook+ obj event-kw key)Returns nil.
(clear-hooks obj event-kw)
Removes all callbacks on the Unity event corresponding to
event-kw, regardless of their keys.
(hook obj event-kw key)
Retrieves a callback from a GameObject obj. event-kw is a
keyword specifying the Unity event of the callback, and key is
the key of the callback.
In other words, retrieves any callback function attached via
(hook+ obj event-kw key callback)or the equivalent.
If key is not supplied, hook uses :default as key. This is the same as
(hook obj event-kw :default)
(state gobj)
(state gobj k)
Returns the state of object go at key k.
(state+ go v)
(state+ go k v)
Sets the state of object go to value v at key k. If no key is provided,
(state- go)
(state- go k)
Removes the state of object go at key k. If no key is provided,
removes state at key default.
(clear-state go)
Removes all state from the GameObject go.
(update-state go k f)
(update-state go k f x)
(update-state go k f x y)
(update-state go k f x y z)
(update-state go k f x y z & args)
Updates the state of object go with function f and additional
arguments args at key k. Args are applied in the same order as
clojure.core/update.
(role obj k)
Returns a hashmap of the state and hooks associates with role k on
GameObject obj.
(roles obj)
Returns a map
defrole macro
(defrole name entry*)
Macro for defining roles quickly. Each entry can be either a key-value pair with a keyword key, such as would normally occur in a map intended as an Arcadia role, or an inlined function definition.
Normal key-value pairs get inserted into the generated map. For example,
(defrole movement
:state {:speed 3}
:update #'movement-update)will expand into
(def movement
{:state {:speed 3}
:update #'movement-update})Inlined function definitions have the following syntax:
(name [args*] body)
name must be the symbol form of an Arcadia hook keyword. A function
intended for the :update hook, for example, should have the name
update:
(defrole movement
:state {:speed 3}
(update [obj k] ...))Each inlined function definition will generate a var, with a name
constructed as follows: <name of role>-<name of hook>
For example, the movement role above will generate a var named
movement-update bound to a function with the provided arguments
and body, and include that var in the generated role map, expanding
into something like:
(do
(defn movement-update [obj k] ...)
(def movement
{:state {:speed 3}
:update #'movement-update}))Note that generating vars is usually a bad idea because it messes with tooling and legibility. This macro does it anyway because the hook functions should serialize in the Unity scene graph, and that requires vars.
Given a persistent representation of a mutable datatype defined via
defmutable, constructs and returns a matching instance of that
datatype.
Roundtrips with snapshot; that is, for any instance x of a type defined via defmutable,
(= (snapshot x) (snapshot (mutable (snapshot x))))
defmutable macro
(defmutable [name [fields*] other*])
Defines a new serializable, type-hinted, mutable datatype, intended
for particularly performance or allocation sensitive operations on a
single thread (such as Unity's main game thread). These datatypes
support snapshotting to persistent data via snapshot, and
reconstruction from snapshots via mutable; snapshotting and
reconstructing are also integrated into role+, state+,
role, and roles.
Instances of these types may be converted into persistent
representations and back via snapshot and mutable. This
roundtrips, so if x is such an instance:
(= (snapshot x) (snapshot (mutable (snapshot x))))If a persistent snapshot is specified as the state argument of
set-state, or as the :state value in the map argument of
role+, the ArcadiaState component will be populated at the
appropriate key by the result of calling mutable on that
snapshot. Conversely, role and roles will automatically convert
any mutable instances that would otherwise be the values of :state
in the returned map(s) to persistent snapshots.
defmutable serialization, via either snapshot or Unity scene-graph
serialization, does not currently preserve reference
identity. Calling mutable on the same snapshot twice will result
in two distinct instances. It is therefore important to store any
given defmutable instance in just one place in the scene graph.
Since they define new types, reevaluating defmutable forms will
require also reevaluating all forms that refer to them via type
hints (otherwise they'll fall back to dynamic
lookups). defmutable-once is like defmutable, but will not
redefine the type if it has already been defined (similar to
defonce).
As low-level, potentially non-boxing constructs, instances of
defmutable types work particularly well with the magic library.
defmutable-once macro
(defmutable-once & [name :as args])
Like defmutable, but will only evaluate if no type with the same name has been defined.