World, spawn, and native APIs
Queries inspect the current runtime world. During Play that is the separate Play world, not the edit scene.
Find and destroy
Scene.FindByName("Target") and Scene.FindById("target-id") return the first live entity matching an exact, case-sensitive name or id. Missing entities return null.
Scene.FindWith<T>() returns a List<Entity> snapshot of live entities with an enabled native or project script component of type T, in scene order:
public void HealTeam() {
foreach (Entity entity in Scene.FindWith<Health>()) {
Health health = entity.GetComponent<Health>();
if (health != null && health.IsAlive()) health.Heal(10);
}
}Snapshots hold at most 1,024 results; an oversized query fails instead of truncating. Id lookups use the scene index. Component queries reuse the world’s component index within a frame; structural changes invalidate it. Index construction and result iteration are metered. Name queries still walk the scene in order. Adding or removing entities does not change an existing snapshot; removed entries read as null.
Scene.Destroy(entity) requires an active Play component. It fires the existing Destroyed Flow event and removes the entity and its children immediately. Missing or expired references are a no-op. Destruction does not end the current method — return after destroying Self when appropriate.
See Scene.
Spawner
Attach Spawner, choose its prefab in the Inspector (that reference also tells the exporter which asset to include), then call typed methods:
public void SpawnWave() {
Spawner spawner = GetComponent<Spawner>();
if (spawner == null) return;
spawner.StopSpawning();
for (int i = 0; i < 3; i++) spawner.SpawnNow();
}SpawnNow() requests one prefab, respecting Max Spawns while ignoring the timer. It returns void: referenced prefabs preload and spawn immediately; an unprepared prefab can still resolve later and reports a warning. SpawnCount is a read-only float counting requests, not successfully completed instances. ResetCount() clears that count. StartSpawning() / StopSpawning() control timed spawning; Running and IsRunning() expose the setting. Mutating commands require Play. Leaving a scene or disposing its world cancels pending prefab results.
The Wave Spawner tutorial covers startup waves, scene-wide Spawner control, and removal by name. Use the prefab Spawned / Ready Flow events when instantiated objects have joined the scene. API: Spawner.
Spawn and SpawnConfigured
Scene.Spawn(prefab, position) returns a preloaded prefab Entity immediately.
Scene.SpawnConfigured(prefab, position, "Configure") calls your synchronous void Configure(Entity spawned) initializer before the spawn cohort’s Start hooks. Failure removes the new cohort before activation; unrelated committed effects are retained. Missing or unprepared prefab data fails immediately and cannot publish a late orphan. The initializer name is a validated literal and participates in rename.
Guide: configured spawning and queries.
Native components
Attach the native component in the Inspector, then look it up with GetComponent<T>(). opal.component declarations are not typed lookup targets.
class NativeHazard : Component {
[Property] float Damage = 10;
void OnCollisionStart(Entity other) {
Health health = other.GetComponent<Health>();
if (health != null) health.TakeDamage(Damage);
Motion motion = other.GetComponent<Motion>();
if (motion != null) motion.RotateTo(30, 0.2);
}
}Every member lives on the class page. The summaries below are the contracts that used to live only in the Scripts chapter.
Health
Read-only Hp, MaxHp, Invulnerable. Change health through TakeDamage, Heal, SetHp, SetMaxHp, Refill, or Kill(). Conditions: IsAlive, IsDead, IsAtFull, HpAtLeast, HpBelow. Damage respects invulnerability; healing respects max HP; existing Health events and Flow listeners still run. TakeDamageResult / HealResult return immutable HealthChange values. Notifications use a bounded FIFO batch under reentrant reactions — Health command contract. Class: Health.
RigidBody2D and SoftBody2D
RigidBody2D: read-only Velocity (Vector2), AngularVelocity (radians per second), Sleeping. Commands: SetVelocity, AddVelocity, ApplyImpulse, SetAngularVelocity, Teleport, SetEnabled, Wake, Sleep. Conditions: IsDynamic, IsKinematic, IsMoving, IsSleeping. Physics continues through the fixed-step engine. Velocity and position use engine world units. RigidBody2D.
SimulationPosition / SimulationRotation (and the matching SoftBody2D properties) read committed world poses — not interpolated presentation. Use velocity, impulse, or Teleport for dynamic movement. Generic transform writes can contend with physics ownership.
SoftBody2D: read-only Enabled, Speed, Deformation, ContactCount, ParticleCount. ApplyImpulse(vector) spreads a total impulse across movable particles; also SetVelocity, ResetShape, SetEnabled. SoftBody2D.
Motion
MoveTo(position, seconds), SnapTo, ScaleTo, RotateTo(degrees, seconds), Shake, Bounce, CancelTweens, ResetHome, IsMoving, IsAnimating. Durations are seconds; rotation targets are degrees, matching Transform. Native easing and completion events still apply. MoveToAsync(position, seconds) returns an owned completion task. Motion.
SpriteAnimator
PlayAsync(animation, restore) returns Task<void> for one exact playback. It loads frames, then completes after the final frame’s hold. Missing or undecodable frames fail the task. restore: true restores the previous sprite on successful completion; Stop, replacement, and cancellation preserve the last displayed frame. Canceling an old task cannot stop a replacement playback.
Existing animation frame labels are marker names. WaitForMarker(name) returns Task<int> with the first reached zero-based frame index in the current or loading playback:
public async Task<int> Attack() {
var animator = GetComponent<SpriteAnimator>();
var playback = animator.PlayAsync(Clip, true);
int release = await animator.WaitForMarker("Release");
await playback;
return release;
}A marker already reached during that playback completes immediately. An unknown label or absent playback fails. Repeated labels keep the first reached index. Canceling only a marker wait leaves playback running. Canceling the containing action also cancels any PlayAsync it owns.
Flow: Play Animation and Wait, Wait for Animation Marker, and the Animation Marker event. Marker timing follows Sprite Animator’s update cadence and authored frame holds — these calls do not move animation into fixed simulation or substitute a timer.
Animation operations accept at most 4,096 frames. Runtime frame holds are finite integers from 1 to 3,600. PlayAsync reserves two native-work units and three allocation-work units per frame before resolving images; exhausting a budget fails the task. Those units account for work, not decoded image bytes. SpriteAnimator.
Other natives
Collider2D, Joint2D, Ragdoll, ParticleEmitter, SceneCamera, Inventory, Stats, AIMover, AbilityCooldown. Full list: class index.
Host-owned multiplayer (Network, [Sync], LocalInput): Multiplayer and Network.
Coordinates and pose
Transform.Position remains parent-local. Transform.WorldPosition is the visual sprite center in scene coordinates. LocalToWorld / WorldToLocal include the parent transform and editable pivot; local zero means the sprite center.
Camera.WorldToScreen / ScreenToWorld use the current rendered viewport, including zoom and shake. Screen coordinates are canvas CSS pixels, not browser page coordinates or physical display pixels.
class TypedMovement : Component {
public async void Move() {
var goal = new Point<World>(280, 240);
await GetComponent<Motion>().MoveToAsync(goal, Seconds(.2));
Point<Local> local = Transform.WorldToLocal(goal);
Point<Screen> screen = Camera.WorldToScreen(goal);
}
}Point<World|Local|Screen> is a position; Vector<World|Local|Screen> is a displacement. Construct with two numeric coordinates; X/Y are read-only. Subtracting same-space points produces a vector; adding that vector moves a point. Different spaces and plain Vector2 need explicit conversion.
Local here means the object’s origin-local coordinates used by the conversion helpers, including its pivot. It does not mean the parent-local position stored in Transform.Position. Transform.WorldPoint supplies the typed world point. Typed conversion calls return typed points; legacy Vector2 calls retain Vector2 results.
Time.Wait accepts Seconds. Time.Delta, Elapsed, SimulationElapsed, and FixedDelta return Seconds alongside the existing float clock members. Motion.MoveTo / MoveToAsync accept a world point and Seconds, converting through the object’s parent. AIMover.MoveToAsync and prefab spawning accept world points. Transform.Rotate accepts Degrees; Math.Sin / Cos accept Radians. Existing float/Vector2 overloads keep previous semantics. Units and coordinate values persist with their semantic schema; changing the unit or space is a schema change, not an implicit conversion. See data, Camera, Transform.