Fio Runtime Architecture

Fio Architecture

Fio uses a unified live-world architecture in which the world being edited is also the world being executed.

Fio does not treat the editor as a separate authoring application that exports a level into a fundamentally different game scene. The editor, simulation systems, gameplay systems and renderer operate on the same live world.

However, Fio 2.5 does not mean that every subsystem directly traverses the world's authoring objects.

The architecture now deliberately separates:

1. The object-oriented authoring model — the world as humans create, inspect and modify it.
2. Dense execution projections — numerical representations derived from that world for subsystems that benefit from bulk processing.

This distinction is fundamental to modern Fio.

The world is authoritative. The projections are disposable execution representations.

The result is neither a traditional compiled level pipeline nor a purely object-oriented runtime.

It is a data-oriented world engine with an object-oriented authoring model.

---

Overview

The basic Fio architecture is:

                              FIO
                               │
                         LIVE WORLD STATE
                               │
             ┌─────────────────┼─────────────────┐
             │                 │                 │
          Geometry          Entities           State
             │                 │                 │
             └─────────────────┼─────────────────┘
                               │
                    OBJECT-ORIENTED WORLD
                         / AUTHORING MODEL
                               │
             ┌─────────────────┼─────────────────┐
             │                 │                 │
          Editor          Simulation          Gameplay
             │                 │                 │
             └─────────────────┼─────────────────┘
                               │
                    DENSE EXECUTION PROJECTIONS
                               │
             ┌─────────────────┼─────────────────┐
             │                 │                 │
         RenderTable       EntityTable       Other Dense
             │                 │              State
             │                 │                 │
             └─────────────────┼─────────────────┘
                               │
                       NUMERICAL EXECUTION
                               │
             ┌─────────────────┼─────────────────┐
             │                 │                 │
          Spatial           Sorting          Simulation
          Queries          / Runs             Batches
             │                 │                 │
             └─────────────────┼─────────────────┘
                               │
                         GPU / RUNTIME

The important property is that the dense execution structures are not alternate world representations.

They are projections of the live world.

The world remains authoritative.

The projections exist because executing large collections of data directly through Python objects is often unnecessary work.

---

The World Is the Runtime

Fio treats a world as more than geometry.

A Fio world contains, among other things:

• geometry
• entities
• spatial relationships
• physical state
• gameplay state
• LogicState
• I/O connections
• simulation state
• residency information
• rendering information
• paths and navigation data
• portals
• terrain
• world-specific runtime state

The editor operates directly on this world.

When Play is activated, runtime systems begin operating on that same world.

Fio does not export the world into another engine before it becomes executable.

Conceptually:

                         LIVE WORLD
                             │
             ┌───────────────┼───────────────┐
             │               │               │
          Geometry        Entities          State
             │               │               │
             └───────────────┼───────────────┘
                             │
                      ENGINE SYSTEMS
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
       Spatial           Simulation          Gameplay
       Systems             Systems            Systems
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │
                  Dense Execution Projections
                             │
                   ┌─────────┴─────────┐
                   │                   │
                Renderer            Simulation

The distinction is important:

The world is authoritative.

The projections accelerate execution.

---

Object-Oriented Authoring, Data-Oriented Execution

Fio does not attempt to eliminate objects from the editor.

Objects are useful for authoring.

They provide:

• identity
• properties
• editor behaviour
• manipulation
• selection
• inspection
• relationships
• persistence
• irregular state
• object-specific authoring semantics

The problem arises when large homogeneous collections are repeatedly traversed through those objects during runtime execution.

Fio therefore uses a deliberate boundary.

              AUTHORING WORLD
                    │
                    │
        Object-oriented model
                    │
                    ▼
          ┌───────────────────┐
          │ Execution         │
          │ Projection        │
          └───────────────────┘
                    │
                    ▼
          Dense numerical data
                    │
                    ▼
             Bulk execution

This allows the editor to remain expressive without requiring the runtime to repeatedly perform object-level work that can be expressed as bulk data transformation.

The governing principle is:

Don't make the CPU repeatedly do work that can be expressed as bulk data transformation.

This is not an assertion that every workload should be vectorised.

It is a rule for identifying where Python object traversal has become unnecessary execution overhead.

---

Dense Execution Projections

Fio 2.5 introduced a more explicit separation between the world model and the data structures used to execute it.

The most important examples are:

• EntityTable
• RenderTable
• dense physics state
• packed render keys
• other subsystem-specific numerical representations

These structures are derived from the live world.

They are not a second source of truth.

Conceptually:

                         LIVE WORLD
                             │
             ┌───────────────┼───────────────┐
             │               │               │
          Geometry        Entities          State
             │               │               │
             └───────────────┼───────────────┘
                             │
                   Derived Execution Data
                             │
             ┌───────────────┼───────────────┐
             │               │               │
        RenderTable      EntityTable       Physics
             │               │               │
             └───────────────┼───────────────┘
                             │
                       Runtime Systems

A projection can be rebuilt or refreshed from the authoritative world.

It does not redefine what the world is.

This makes the execution representation disposable, testable and optimisable without corrupting the authoring model.

---

EntityTable

EntityTable is Fio's dense entity execution projection.

It exists to remove repeated runtime inspection of Python entity objects.

Rather than repeatedly asking every ent