Reaktor Arena

Reaktor Arena is a small Unreal Engine based simulation lab for testing ideas that are hard to understand from static docs, code snippets, or non-interactive diagrams: agents, abilities, effects, symbolic planners, utility AI, machine-learning policies, event traces, graph execution, and runtime debugging.

It should not start as a Reaktor runtime integration. The first versions should be a standalone Unreal project that borrows Reaktor's vocabulary and design pressure, then produces lessons, traces, datasets, and high-level orchestration boundaries that Reaktor can later consume.

• Host Unreal Engine 5 project
• Initial scope local simulation, combat sandbox, AI/algorithm debugger
• Reaktor dependency in v1 none
• Future bridge Reaktor chooses high-level actions and scenario graphs; Unreal executes physics, animation, and frame-level simulation
• Primary users Reaktor engineers, AI/agent researchers, systems designers, educators, advanced users learning graph/runtime topics
• First wow moment click an enemy, see its decision scores and trace, change one weight, replay the scenario, and watch behavior change

1. Why this exists

Several Reaktor ideas are powerful but too abstract when presented only as architecture:

The lab gives Reaktor a place to validate ideas before they harden into framework APIs. It also gives new contributors a way to learn advanced topics by manipulating running systems instead of reading definitions.

2. Product intent

Opening Arena should feel like entering an AI and systems laboratory:

• Spawn agents.
• Assign abilities.
• Select an AI backend.
• Run a scenario.
• Pause the world.
• Inspect the selected agent.
• See why an action was chosen.
• Modify weights, rules, or planner costs.
• Replay from the same seed.
• Compare metrics across AI systems.
• Export traces for later analysis.

The core loop is:

design agent
  -> run scenario
  -> observe behavior
  -> inspect decision
  -> tune rule, weight, or graph
  -> replay from seed
  -> compare outcome

The first experience should be narrow and strong:

One arena.
One player.
Two enemy bots.
Same abilities.
Enemy A uses Behavior Tree.
Enemy B uses Utility AI.
Pause.
Click either enemy.
See the exact perception, memory, scores, chosen action, ability state, and recent events.
Change one utility weight.
Replay.

3. Non-goals for v1

Do not let the first version become a full game. Avoid:

• Multiplayer.
• Open world.
• Quests.
• Dialogue.
• Inventory.
• Loot.
• Cinematics.
• Photorealistic art direction.
• Full RPG balance.
• Full Reaktor runtime embedding.
• Deep reinforcement learning as the first AI milestone.
• Editable external graphs before the runtime inspector is useful.

The sharp v1 scope is:

small combat simulation
  + inspectable AI
  + explicit abilities/effects
  + event timeline
  + deterministic scenarios
  + algorithm visualizers

4. Design constraints

Arena should follow the same engineering values as Reaktor without pretending it is Reaktor:

1. Runtime state must be inspectable. If an agent can act on a fact, the user should be able to inspect that fact.
2. Causality must be visible. Every meaningful state change should have a trace event and a source.
3. AI must not read perfect world state by default. Agents act on perception and memory, not omniscience.
4. Scenarios must be reproducible. Seed, layout, archetypes, config, and initial state belong in scenario data.
5. Debugging comes before editing. Text inspector -> timeline -> overlays -> read-only graph -> editable graph.
6. C++ owns primitives. DataAssets and Blueprints configure and assemble behavior; primitives stay testable and reviewable.
7. Unreal owns physical execution. Movement, animation, collision, physics, and frame-level interaction stay native.
8. Reaktor later owns orchestration. The clean bridge is high-level goals, action selection, scenario scripting, trace export, and graph visualization.

5. Unreal architecture

The project should use familiar Unreal concepts instead of inventing a parallel engine.

Suggested module layout:

ReaktorArena
  Core
    agent identity
    tags
    event bus
    debug trace
    deterministic clock/seed
    scenario runtime

  Combat
    attributes
    abilities
    effects
    cooldowns
    hit detection
    gameplay cues

  AI
    perception
    memory
    behavior tree adapter
    utility AI
    GOAP planner
    state machines
    policy inference adapter
    decision debugger

  Simulation
    arena layouts
    spawn rules
    resources
    hazards
    waves
    reset/replay

  Debug
    agent inspector
    event timeline
    overlays
    algorithm visualizers
    read-only graph view
    metrics comparison

  Bridge
    trace export
    scenario import/export
    high-level action protocol
    future Reaktor adapter

Suggested class shape:

AReaktorArenaGameMode
AReaktorArenaGameState
AReaktorArenaScenarioManager
AReaktorAgentCharacter
AReaktorAIController

UReaktorAgentComponent
UReaktorAttributeComponent
UReaktorPerceptionMemoryComponent
UReaktorDecisionComponent
UReaktorUtilityAIComponent
UReaktorGOAPPlannerComponent
UReaktorDebugTraceComponent
UReaktorArenaEventBus

UReaktorAbilitySystemComponent
UReaktorAttributeSet
UReaktorGameplayAbility
UReaktorGameplayEffectTypes

UReaktorScenarioDataAsset
UReaktorAgentArchetypeDataAsset
UReaktorAbilitySetDataAsset
UReaktorUtilityActionDataAsset
UReaktorGOAPActionDataAsset

6. Agent model

Every character in the arena is an agent. An agent has:

• Body.
• Attributes.
• Abilities.
• Active effects.
• Perception.
• Memory.
• Goals.
• Decision backend.
• Debug trace.
• Metrics.

Conceptually:

Agent
  -> BodyComponent
  -> AttributeComponent
  -> AbilityComponent
  -> PerceptionComponent
  -> MemoryComponent
  -> DecisionComponent
  -> PlannerComponent
  -> CombatComponent
  -> DebugInspectableComponent

The most important rule: agent state should be explainable. If an enemy retreats, the inspector should be able to answer:

What did it perceive?
What did it remember?
Which actions were legal?
How were actions scored?
Which action won?
Which ability was activated?
Which effects changed state?
Which event caused the next decision?

This is the same question Reaktor eventually needs to answer for app and system graphs:

Why did this node execute?
Why did this effect apply?
Why was this event routed?
Why did this policy deny the operation?
Why did this agent propose that patch?

7. Arena world

The first map should be intentionally small:

• One contained arena.
• Spawn points.
• Obstacles.
• Cover.
• Health pickups.
• Stamina pickups.
• Hazard zones.
• Debug grid.
• NavMesh.
• Scenario reset button.

Then add scenario layouts:

The world should be simple enough that behavior is legible. Arena art direction should serve debugging: clear silhouettes, readable distances, strong affordances, and overlays that remain usable while paused.

8. Combat runtime

Combat is the first physical domain because it naturally combines state, events, planning, timing, and feedback.

Core features:

• Health.
• Stamina.
• Cooldowns.
• Poise/stagger.
• Blocking.
• Dodging.
• Damage.
• Healing.
• Hit reactions.
• Death/reset.
• Status effects.
• Target lock.

The ability model should be explicit:

Ability
  id
  displayName
  tags
  activation condition
  cost
  cooldown
  action phase
  cancel rules
  effects
  cues
  debug trace

Example:

Ability: DashStrike

Activation:
  target within 800 units
  stamina >= 30
  not stunned
  not already attacking

Execution:
  rotate to target
  dash toward target
  wait for contact window
  apply damage effect
  apply knockback effect
  emit hit cue

Cooldown:
  6 seconds

Tags:
  Ability.Melee.Dash
  State.Attacking
  Cost.Stamina

Effects are the bridge between game combat and generic graph mutation:

Effect
  source
  target
  magnitude
  duration
  stacking rule
  tags
  application policy
  debug event

Example:

Effect: Burn
Source: Fireball
Target: Enemy
Duration: 5 seconds
Tick: 10 damage/sec
Stacking: refresh duration
Tags: Effect.Fire, Effect.DamageOverTime

Reaktor mapping:

Ability -> executable behavior
Effect -> explicit mutation/event packet
Cue -> observable side effect
GameplayTag -> semantic routing key
Cooldown -> policy and temporal constraint

9. Perception and memory

Agents should not query perfect state unless a scenario explicitly grants it. Perception should include:

• Sight.
• Hearing/noise.
• Damage awareness.
• Line of sight.
• Last known target position.
• Nearby allies.
• Nearby enemies.
• Nearby resources.
• Threat level.
• Confidence.

Memory should persist selected observations:

EnemyMemory
  targetId
  lastSeenLocation
  lastSeenTime
  estimatedHealth
  lastKnownVelocity
  threatScore
  confidence

The inspector should show both current perception and remembered state:

Perception:
  Sees Player: true
  Distance: 420
  Line of sight: true

Memory:
  Last seen: 0.7s ago
  Last position confidence: 0.91
  Recent damage source: Player.LightAttack

This models one of Reaktor's most important runtime patterns: systems rarely act on raw truth; they act on projections, caches, observations, and stale facts with confidence.

10. Decision backends

Arena should support multiple AI backends because each teaches a different idea.

The recommended order is:

Behavior Tree
  -> Utility AI
  -> GOAP
  -> hybrid symbolic + utility
  -> ML/RL policy adapters

10.1 Utility AI

Utility AI is likely the strongest early Reaktor lesson because it is algorithmic, tunable, and inspectable.

Example:

Attack score =
  target_visible * target_in_range * stamina_factor * aggression

Retreat score =
  low_health * enemy_nearby * no_stamina * self_preservation

UseCover score =
  ranged_threat * nearby_cover_quality * target_visible

Inspector:

Action scores:
  Attack: 0.72
  Dodge: 0.31
  Retreat: 0.88
  Heal: 0.45

Chosen:
  Retreat

Reason:
  health low
  target visible
  stamina below dodge threshold
  selfPreservation weight = 0.9

10.2 GOAP

GOAP turns symbolic AI into visible behavior.

Goal:
  PlayerDead

Action: AttackTarget
  Preconditions:
    HasWeapon = true
    TargetInRange = true
    Stamina > 20
  Effects:
    TargetDamaged = true
    StaminaReduced = true
  Cost:
    3

Chosen plan:
  MoveToTarget
  -> StunTarget
  -> HeavyAttack
  -> Retreat

The plan debugger should show:

• Candidate plans.
• Chosen plan.
• Cost.
• Failed preconditions.
• Replan reason.
• Which observed fact invalidated the previous plan.

10.3 Machine-learning policy adapters

ML should come after deterministic and symbolic systems, not before them. The first ML integration should be an adapter boundary, not a training platform:

ObservationBuilder
  -> policy inference adapter
  -> proposed high-level action
  -> action guard
  -> Unreal ability execution

The policy should propose high-level actions:

• Attack.
• Retreat.
• UseCover.
• Heal.
• ChaseTarget.
• AssistAlly.
• CollectResource.

It should not control every frame of movement in early versions. That boundary keeps Arena debuggable and keeps Unreal responsible for physical execution.

The ML inspector must include:

• Observation fields.
• Policy version.
• Output scores/logits if available.
• Chosen action.
• Action guard result.
• Reward events.
• Fallback reason when symbolic safety overrides the policy.

11. Algorithm playground

Arena should make algorithms feel physical, not academic. Initial algorithms:

• A*.
• Dijkstra.
• Flow fields.
• Influence maps.
• Utility scoring.
• GOAP planning.
• Behavior trees.
• FSM/HFSM.
• Steering behaviors.
• Flocking.
• Line-of-sight queries.
• Cover selection.
• Target selection.
• Resource allocation.
• Squad coordination.

Each algorithm should have a visual debugger:

A*:
  open set
  closed set
  final path
  path cost

Influence map:
  red = danger
  blue = safe
  green = resources

Utility AI:
  score bars
  winning action
  score formula inputs

GOAP:
  current goal
  candidate plans
  chosen plan
  failed precondition

The target is not LeetCode-style algorithm practice. The target is systems intuition: how algorithms behave when time, uncertainty, perception, cost, and physical space interact.

12. Debug studio

The debug studio is the real product surface. It should eventually include:

Agent inspector

Click any agent and inspect:

• Identity.
• Current state.
• Attributes.
• Active ability.
• Active effects.
• Cooldowns.
• Gameplay tags.
• Current goal.
• Current plan.
• Perceived actors.
• Memory.
• Utility scores.
• Path state.
• Recent events.
• Decision history.
• Metrics.

Event timeline

Every meaningful runtime change should emit an event:

12.031 Player pressed LightAttack
12.033 Ability.LightAttack activated
12.105 AnimNotify.HitWindowStarted
12.128 Enemy_01 entered hitbox
12.129 Effect.Damage applied: 18
12.130 Cue.HitSpark emitted
12.131 Enemy_01 Health: 72 -> 54
12.170 Enemy_01 UtilityAI chose Retreat

Timeline features:

• Pause.
• Step frame.
• Filter by agent.
• Filter by tag.
• Filter by ability.
• Filter by effect.
• Click event to inspect context.
• Jump from event to graph node once graph visualization exists.

Overlays

Useful overlays:

• Vision cones.
• Hearing radii.
• Nav paths.
• Open/closed pathfinding sets.
• Influence heatmaps.
• Cover quality.
• Line of sight.
• Threat fields.
• Ability ranges.
• Hit windows.
• Cooldown clocks.

Read-only graph view

Do not begin with editable graphs. Start with visualizing execution:

Input.Attack
  -> ActivateAbility.LightAttack
  -> PlayMontage
  -> WaitForHitWindow
  -> TraceWeapon
  -> ApplyDamage
  -> EmitCue
  -> EndAbility

Then decision graphs:

PerceiveTarget
  -> UpdateMemory
  -> ScoreActions
  -> SelectAction
  -> ActivateAbility

Recommended order:

text inspector
  -> event timeline
  -> world overlays
  -> read-only graph visualization
  -> editable graph
  -> external Reaktor bridge

13. Scenario harness

Scenarios should be data-driven and reproducible.

Example scenario names:

• Duel_OneVsOne
• Swarm_OneVsTen
• Cover_RangedEnemies
• Boss_PhaseTest
• UtilityAI_RetreatTest
• GOAP_ResourceTest
• Squad_CoordinationTest

Scenario fields:

Scenario
  id
  map
  seed
  agents
  spawn points
  agent archetypes
  AI backend
  initial resources
  win condition
  debug options
  time limit
  metrics profile

Example:

Scenario: Utility_Retreat_Test

Player:
  spawn: Center
  abilities: LightAttack, DashStrike

Enemies:
  count: 3
  archetype: MeleeChaser
  AI: UtilityAI
  aggression: 0.4
  selfPreservation: 0.9

Goal:
  observe retreat behavior when health < 30%

This maps directly to Reaktor's shadow and replay thinking: capture the starting state, run the behavior, compare the result, and make debugging reproducible.

14. Metrics and comparison

Basic metrics should arrive early:

• Time alive.
• Damage dealt.
• Damage taken.
• Abilities used.
• Dodges used.
• Successful blocks.
• Failed attacks.
• Average distance to target.
• Decision changes per minute.
• Path length.
• Time spent stuck.
• Plan failures.
• Replans.
• Effect applications.
• Timeline event count.

Comparison view:

Behavior Tree Enemy:
  survival: 41s
  damage: 120
  bad decisions: 8

Utility AI Enemy:
  survival: 58s
  damage: 95
  bad decisions: 3

GOAP Enemy:
  survival: 73s
  damage: 80
  bad decisions: 2

Arena should also export trace and metric bundles so Reaktor docs, workbench prototypes, and future agents can analyze them outside Unreal.

15. Future Reaktor bridge

The bridge is important, but it should not be built first.

Good first boundary:

Reaktor = planner/orchestrator
Unreal = physical executor

Reaktor may later provide:

• High-level action selection.
• Ability graph import.
• Decision graph import.
• Scenario scripting.
• Wave spawning.
• Effect routing policies.
• Trace export/import.
• Agent behavior config.
• Debug explanations.

Do not start with:

Reaktor controls every frame of character movement.
Reaktor owns physics.
Reaktor owns animation state.
Reaktor replaces Unreal AIController.

Those boundaries create too much latency, complexity, and debugging ambiguity. Arena should first prove that high-level graph orchestration can make native simulation more understandable.

Bridge protocol sketch

Unreal -> Reaktor
  scenario.started
  perception.updated
  decision.requested
  ability.activated
  effect.applied
  metric.recorded
  timeline.event

Reaktor -> Unreal
  chooseAction(agentId, context)
  updateWeight(agentId, key, value)
  setScenarioConfig(config)
  requestReplay(seed)
  annotateTrace(eventId, explanation)

Use JSON first for iteration. Consider FlexBuffer later only if trace volume or native bridge performance requires it.

16. Reaktor lessons table

17. Roadmap

v0.1 - Combat sandbox

Goal: basic playable loop.

• Movement.
• Camera.
• Light/heavy attack.
• Dodge.
• Block.
• Health/stamina.
• One enemy.
• Death/reset.

v0.2 - Ability and effect runtime

Goal: structured actions.

• Ability definitions.
• Attributes.
• Effects.
• Cooldowns.
• Gameplay tags.
• Ability sets.
• Debug events for ability lifecycle.

v0.3 - Perception and Behavior Tree

Goal: first intelligent enemy.

• AIController.
• Blackboard.
• Behavior Tree.
• NavMesh.
• Perception.
• Patrol/chase/attack/retreat.
• Inspector for BT state.

v0.4 - Utility AI

Goal: inspectable decision-making.

• Utility actions.
• Score functions.
• Decision inspector.
• Score visualization.
• Runtime tuning.
• Scenario comparison.

v0.5 - GOAP planner

Goal: symbolic planning.

• Actions.
• Preconditions.
• Effects.
• Goal selection.
• Plan debugger.
• Failed-plan explanation.

v0.6 - Debug studio

Goal: make Arena educational.

• Agent inspector.
• Event timeline.
• Event filters.
• Path visualization.
• Perception visualization.
• Influence maps.
• Metrics.
• Scenario replay.

v0.7 - Read-only graph visualization

Goal: make the Reaktor connection visible.

• Ability execution graph.
• Decision graph.
• Effect graph.
• Event routing graph.
• Trace-linked graph nodes.

v0.8 - Bridge prototype

Goal: external orchestration.

• Export events.
• Import high-level action graph.
• JSON protocol.
• Reaktor chooses high-level actions.
• Unreal executes native actions.

v0.9 - ML policy lab

Goal: compare deterministic, symbolic, and learned decision systems.

• Observation schema.
• Policy inference adapter.
• Reward event stream.
• Offline trace dataset export.
• Fallback guards.
• Side-by-side comparison with Utility AI and GOAP.

18. Definition of done

The first serious version is done when:

• A user can run one arena scenario.
• A player can fight two or more enemy archetypes.
• One enemy uses Behavior Tree and one uses Utility AI.
• Abilities, effects, attributes, cooldowns, and tags are visible in the inspector.
• The world can be paused and stepped.
• A selected agent explains its current action.
• A timeline records ability, effect, decision, and metric events.
• A scenario can be reset and replayed from the same seed.
• At least one algorithm overlay is useful, not decorative.
• Metrics compare two AI backends.
• No Reaktor runtime integration is required.

19. Risks

See also

• Reaktor Visual Language - Blueprint-style graph authoring and execution semantics.
• The Reaktor Control Plane - governed Observe/Call/Change model for humans and agents.
• Reaktor Unified System Graph - whole-product graph, desired/observed state, and operation providers.
• Reaktor Actor Model - stateful runtime entities with mailboxes and owned state.
• Browser-Local AI for Reaktor - local AI as a suggestion and explanation tier.
• Performance and Observability - traces, metrics, budgets, and graph overlays.
• Shadow Dev Environment - production-shaped replay and comparison.

Related docs

• Visual Language - Use when designing the node-based authoring/orchestration language and its editor, compiler, and agentic surface.
• Graph Kernel - Use to keep the core language small while modules add vocabulary.
• Strategic Roadmap - Use for strategic framing and product sequencing.
• Competitive Landscape - Use when clarifying Reaktor's graph-native differentiation, competitor pressure, and where to integrate instead of compete.
• Mega-Scale Strategy - Use for enterprise-adoption strategy, the open-source vs commercial split, and sequencing the distributed-tier roadmap without diluting the single-threaded-actor core.
• Control Plane - Use when exposing Reaktor safely to humans and agents.