Scripting API · Ara.Runtime
C# scripting API
Gameplay is plain C# 14 on .NET 10, hosted inside the engine. These are the public types of
Ara.Runtime, with signatures and docs read from the shipped assembly. New to scripting? Start with the scripting overview.Classes
- AnimationTyped inputs to an entity's authored native animation controller.
- BehaviourA per-entity object with Unity-like ergonomics that holds no authoritative state. Declare sealed partial class Door : Behaviour with [Property] public partial float OpenAngle { get; set; }: the generator backs each property with a column of the generated Door data component, so the value is saved, replicated and survives reload. Other instance fields must be TransientAttribute caches (ARA0101).
- EngineComponentsEngine components in stable binding order.
- InputReplayable player actions at the current fixed tick. Behaviours and commands only.
- LogLogging to the host console and log.
- MissingComponentExceptionThrown when an entity lacks a component that code asked for.
- MovementFixed-tick controls for native physics characters.
- NavigationServer-authoritative goals for authored NavAgent components; paths remain in ECS.
- UnitsUnit symbols for UnitAttribute, as stored in the Schema DB.
- WorldRandom access to ECS data from behaviours and commands (which run with exclusive world access). Systems never use this: they declare their components as parameters so the scheduler can run them in parallel. References stay valid until the current callback returns; structural changes go through Commands.
Structs
- AcousticMaterialSurface acoustics for reflection, scattering and transmission.
- AcousticPortalAn opening (door, window, archway) connecting two zones. An empty zone name is outdoors.
- AcousticSourcePer-source acoustic behaviour, alongside AudioSource. Optional: sources without it use AcousticSource::default().
- AcousticSurfaceAcoustic surface of static geometry or a collider. The physics ray adapter maps hit bodies to this component; absent components read as generic.
- AnimatorSkeletal animation for this entity's MeshRenderer.model, compiled to an ara-anim program: the controller document when set, else an idle state and a move state whose 1D blend tree is driven by the entity's ground speed, cross-faded at moveThreshold.
- AudioGraphSourcePlays a procedural audio graph (an ara-audio-graph graph document, domain audio) from this entity, spatialized and attenuated by its AudioSource (whose clip stays empty). Gameplay writes parameters and bumps triggers; the audio presenter forwards changes sample-accurately at the next control frame.
- AudioListenerPresentation listener, usually copied from the local player's camera component.
- AudioSourceDeclarative sound intent. Playback cursors and decoder state are presentation only.
- BrainRuns a behaviour on this entity (authoring).
- CameraA viewpoint looking along the entity's local -Z axis. The lowest priority wins.
- Camera2dOrthographic view. Pixel mode uses integer zoom and nearest texel sampling.
- CharacterControllerPredicted capsule movement: slopes, stairs, moving platforms, crouching and pushing.
- CharacterController2dKinematic capsule character: slopes, steps, ground snapping and pushing. The entity needs no RigidBody2d/Collider2d; the controller owns its capsule.
- CharacterInputPer-tick character intent: replay this input exactly once before the rigid-body step.
- CharacterInput2dPer-tick character intent, read exactly once by each boundary. Gameplay writes it before the physics system; it is not cleared, so held input repeats.
- CharacterMotionCharacter support and stance mirrored at every fixed boundary.
- CharacterMotion2dCharacter support mirrored at every fixed boundary.
- ColliderCollision geometry, material, layer and trigger settings.
- Collider2dCollision geometry, material, layer and trigger settings for a RigidBody2d.
- ColorA linear RGBA color (the schema's color type). Defaults to opaque white in the schema.
- CommandContextWhat a CommandAttribute command sees: the tick, the caller, a deterministic Rng, structural Commands and cues. A ref struct, so commands cannot capture it in lambdas or keep it past the call.
- CommandResultThe outcome of a command: Ok, or a rejection made with Reject. A rejected command leaves the world unchanged.
- CommandsStructural changes (spawn, despawn, add, remove) and cues, buffered and applied by the host at the next sync point in a deterministic order. Systems take it as a ref Commands parameter; behaviours and commands get one from their context.
- EntityA generation-checked handle to an entity in the ECS world: the engine's Entity::to_bits (a complemented index in the low 32 bits, the generation in the high 32). A despawned entity's handle never becomes valid again, so a stale handle reads as missing instead of aliasing a new entity. Use IsAlive or Has; there is no overloaded null equality.
- EnvironmentProcedural sky radiance and camera exposure. The first in stable-ID order wins.
- FlipbookTick-driven flipbook state, wholly contained in an ECS component.
- FlipbookFrameOne deterministic flipbook frame.
- FollowCameraThird-person orbit rig: places this entity behind target, steered by Look.
- FrameOne presented frame (variable rate), passed to Behaviour.OnFrame.
- HeightFogExponential height fog lit by the sun, the sky and local lights (volumetric shafts where shadows cut the beams). Density halves every falloff × ln 2 metres above baseHeight. The first entity in ID order wins.
- JointJoint on a body; connection zero anchors to the world. Anchors/axes are world-space.
- LightA light at the entity's world position. Edits apply live in play.
- Light2dPoint light for an explicitly lit sprite; Z provides normal-map elevation.
- LocomotionClipOne clip of a locomotion blend and the ground speed it represents.
- MeshRendererDraws geometry at the entity's interpolated world transform.
- MusicSourcePlays a .music document's interactive score (segments, transitions, intensity layers) from this entity, non-spatial. Presentation intent: gameplay writes intensity and segment; the audio presenter follows them.
- NavAgentDimensions, speed and permitted areas of one navigation agent.
- NavAgentTypeA named agent type: its own baked mesh (dimensions) and traversal costs. Agents select it through NavAgent.profile == profile.
- NavAreaArea label and cost policy for the collision-geometry producer and query filters.
- NavLinkAuthored off-mesh connection in world space (jump, ladder or scripted passage).
- NavMeshSurfaceAuthored raw-geometry navigation surface; its derived mesh is content-addressed.
- NavObstacleDynamic obstacle: an axis-aligned box centred on the entity's NavPosition. Carve/Area changes publish after NavConfig::rebake_latency_ticks; until then (and always for Avoid) agents avoid it locally.
- PerceiverAn AI's senses: a sight cone with peripheral vision, hearing and memory.
- PhysicsIdStable simulation identity; nonzero and unique within a physics world.
- PhysicsPoseResolved world-space pose in meters. Hierarchy/scale resolution runs before physics.
- PhysicsPose2dWorld-space 2D pose, written back by the solver at every completed boundary.
- PlayerControlDrives this entity's CharacterController from Move, Sprint and Jump, relative to its camera rig's yaw.
- PostOverrideOne group of settings a post-process volume overrides: pick the group in module, then tick the properties to change. Unticked properties are left to lower-priority volumes and the defaults.
- PostProcessVolumeA region whose post-processing overrides blend in as the camera approaches and enters it. Volumes apply in ascending priority (ties in entity ID order); each property one overrides moves toward its value by the volume's weight at the camera. Properties no volume overrides keep the engine defaults. Scenes saved with the former PostProcess component load as one global volume that overrides everything.
- PrimitiveMaterialOverrideOne native material graph/instance replacing a selected model primitive's material.
- ReverbZoneA room or space with its own reverb. The listener's zone drives the room reverb; sources in other zones reach the listener through portals.
- RigidBodyRigid-body authoring settings; simulation state is written to pose and velocity.
- RigidBody2dRigid-body authoring settings; simulation state is written to pose and velocity.
- RngDeterministic random numbers (PCG-XSH-RR). Seeds come only from the context: the session seed, the tick, and a stream key such as the system and entity, so results are identical across machines, thread counts and chunk splits. Never use System.Random in simulation code (ARA0200).
- SkyAtmosphereA physical sky and aerial perspective lit by the scene's directional light. The sun's elevation sets the time of day; without this component the scene uses its Environment gradient. The first entity in ID order wins.
- SpriteA batched sprite with optional normal-mapped 2D illumination.
- StimulusSomething perceivers can see and remember (players, corpses, thrown objects).
- StreamedWorldStreams a .world's cells into play around the players (ara-runtime-world). Put it on one entity of the level scene; the cell documents stay out of the projection and arrive at tick boundaries. With a Terrain, navigation then follows the resident TerrainChunks.
- TerrainPuts a .terrain heightfield (and its .foliage scatter) in play: rendered by the landscape renderer, walkable for navigation, solid where TerrainChunks exist.
- TerrainChunkCollision for one terrain tile (grid coordinates of the level's Terrain). Author these in world cells to stream collision with the cells.
- TickThe fixed simulation tick that every system, behaviour and command sees.
- TileColliderSource2dOwnership marker for generated colliders, separate from gameplay body state.
- TileDefinitionA tile's visual, terrain, collision and lighting definition.
- TileLayerOne map layer with stable identity, source cells and independent painter order.
- TileRuleFirst matching rule wins. Masks use GridLayout::neighbors bit order; a neighbor "matches" when its tile's definition has the rule's terrain.
- TilemapCanonical text source for a tilemap. Binary chunks are derived cache products.
- TransformPosition, rotation and scale of an entity relative to its parent.
- VehicleFour-wheel engine/automatic-gearbox vehicle, using S6's stable defaults.
- VehicleInputReplayable driver intent consumed every fixed tick.
- VehicleTelemetryVehicle drivetrain and suspension state mirrored into ECS after each tick.
- VelocityAuthoritative velocity, synchronized at tick boundaries.
- Velocity2dAuthoritative velocity, synchronized at tick boundaries.
- VisualEffectA GPU particle effect drawn at this entity. Presentation only: gameplay reads ara-vfx CPU events, never GPU particles. effect names a cooked library effect (campfire, sparks, depth_sparks, magic_swirl, smoke, muzzle_flash, rain, dust).
- WandererServer-side AI: walks the navmesh to random points inside a box, pausing between.
Interfaces
Attributes
- ColorPickerAttributeEdits a linear RGB(A) value with the engine's colour picker.
- CommandAttributeDeclares a gameplay command: a static partial class with public static CommandResult Execute(ref CommandContext ctx, Entity target, ref C component, ...). Plain parameters become the params type agents and tools call it with; ref/in component parameters bind to the target entity's components. Commands are synchronous and capture no managed state, so they are prediction- and undo-safe.
- ComponentAttributeDeclares a blittable component stored in engine ECS columns. Apply to a partial struct; the source generator registers it in the Schema DB (name, fields, units, ranges, docs), so it appears in reflection.json and agent tools.
- CueAttributeDeclares a presentation cue (sound, VFX trigger) that commands and systems emit with Cue(...). Cues are reported to the host and never change simulation state.
- DefaultAttributeThe schema default of a field: a number, bool or string, or a vector's components.
- EngineComponentAttributeMarks a component generated from the Rust Schema DB (engine-owned; do not apply by hand).
- ExampleAttributeAn example params object (JSON) for a command, shown to agents and in docs.
- ExposeAttributeNetwork exposure of a CommandAttribute command (enforced by the netcode layer).
- FormerlySerializedAsAttributeA former field name; files using it are renamed on read (Unity's attribute, same meaning).
- HeaderAttributeInspector group heading for this field and the ones after it.
- MaxAttributeAn inclusive upper bound.
- MinAttributeAn inclusive lower bound.
- PropertyAttributeBacks a Behaviour's partial property with an ECS column: the value lives in the behaviour's generated data component, so it is saved, replicated and survives reload.
- QueryAttributeTurns a static void Run(ref A a, in B b, in Tick t) method into a chunk-batched system. ref component parameters are writes, in parameters reads; the read/write sets go to the scheduler, so non-conflicting systems run in parallel. Optional parameters: Entity, in Tick, ref Rng, ref Commands, and ResourceAttribute structs.
- RangeAttributeInclusive numeric bounds (Unity's [Range], same meaning).
- ReplicateAttributeNetwork replication of a field (codecs and interpolation stay in the engine).
- ResourceAttributeDeclares a world singleton (game rules, tuning). Systems take it as an in or ref parameter; behaviours and commands use Resource.
- SimulationAttributeMarks simulation code (a type or the whole assembly): it must be deterministic, so ARA0200 rejects async, wall-clock time, System.Random, I/O and threads in it.
- TooltipAttributeInspector tooltip text; used as the field doc when there is no XML doc comment.
- TransientAttributeA presentation-only cache on a Behaviour: not saved, not replicated, dropped on reload. Every other Behaviour instance field is an error (ARA0101).
- UnitAttributePhysical unit of a numeric field, by schema symbol (see Units).
- WithAttribute<T>Restricts a QueryAttribute system to entities that also have T.
- WithoutAttribute<T>Restricts a QueryAttribute system to entities without T.
Enums
- AttenuationDistance rolloff model, evaluated in meters.
- AudienceRecipients of a replicated field.
- CallerWho may send a networked command.
- ColliderKindPrimitive or cooked geometry selection. Cooked geometry is resolved by the asset worker.
- ColliderKind2dConvex 2D geometry selection; 2D never reuses the 3D shape vocabulary.
- ExecuteOnWhere a networked command runs.
- ExposureModeHow the camera exposes the scene (a post-process volume's exposure override).
- GridLayoutTile coordinate layout; hex is axial and pointy-topped.
- InterpolateHow remote views smooth a replicated field between snapshots.
- JointKindJoint primitive implemented by the backend.
- LightKindHow a light emits.
- LinkKindHow agents traverse an off-mesh link. Animation reads it from NavAgentState.traversal (an intent), never through a call.
- MaterialPresetNamed surface materials with Steam Audio's published values.
- MeshShapeBuilt-in procedural geometry for gray-box levels.
- MotionTypeHow a rigid body moves; kinematic targets are runtime intents.
- MotionType2dHow a rigid body moves; kinematic bodies follow their written pose.
- ObstacleModeHow the navigation reacts to a dynamic obstacle.
- PostModuleThe group of settings one PostOverride entry changes.
- ToneMappingThe display transform that compresses scene radiance into the screen's range.
- VolumeShapeWhere a post-process volume applies.
- ZoneShapeReverb zone volume shape.