Thrive

Table of Contents

1. Stage

Top-level scene management.

Base classes are under the directory src/general/base_stage

  • class StageBase
    • Node world: The World Godot node
    • Node : This is the Godot node that sprites are added.
    • PauseMenu pauseMenu
    • Control hudroot
    • bool gameover
    • GameWorld GameWorld
    • virtual void SetupStage (): call virtual void OnGameStarted
    • void _Process (double delta): load stage if not loaded, and GameWorld.Process((float)delta)
  • class CreatureStageBase <TPlsyer, TSimulation> : StageBase
    • TSimulation WorldSimulation
    • override void _Process (double delta): pass to StageBase, handle respawn and extinction

1.1. MicrobeStage

Under the directory src/microbe_stage

  • class MicrobeStage : CreatureStageBase<Entity, >
    • override void _Ready (): Setup HUD, fluid current, and SetupStage
    • override void SetupStage (): initializes system and cloud, and call OnGameStarted via base.SetupStage
    • override void OnGameStarted (): call SpawnPlayer
    • override void SpawnPlayer () spawn using SpawnMicrobeWithoutFinalizing and attach player specific components
    • override void _Process (double delta): call base.Process, and run ProcessAll

1.1.1. Spawn

  • static class SpawnHelpers
    • static float (worldSimulation, species, location, ...): create new entity and attach components via CommandBuffer recorder.

2. GameWorld

The global informations of the world, in contrast to the information about the world that we can see: World.

  • class GameWorld
    • Dictionary<uint, Species> worldSpecies
    • TimedWorldOperations TimedEffects
    • Species PlayerSpecies
    • PatchMap Map
    • MicrobeSpecies CreatePlayerSpecies ()
    • DayNightCycle LightCycle
    • void Process (float delta): LightCycle.Process(delta)
    • GameWorld (WroldGenerationSettings settings, Species? startingSpecies = null): add effects to the game, create the player cell,

3. Physical World

Under the directory src/engine/physics, which uses the library in src/native/ which is compiled against third_party/JoltPhysics/.

  • class PhysicalWorld
    • ProcessPhysics

3.0.1. NativePhysicsBody

It contains the IntPtr called nativeInstance, which is used in the physical world.

4. WorldSimulation

Base under src/general/base_stage

  • abstract class WorldSimulation
    • protected readonly World entites: Arch.Core.World from the Arch ECS
    • World EntitySystem: wrapper for the readonly variable entities.
      • World EntitySystem => entities; means World EntitySystem { get { return entities; } }
    • Vector3 PlayerPosition
    • float WorldTimeScale: default to 1
    • bool (float delta): run ProcessLogic(delta) and ProcessFrameLogic(delta)
    • virtual bool ProcessLogic (float delta): run OnProcesFixedLogic(accumulatedLogicTime), and OnProcessPhysics(accumulatedLogicTime)
      • Not overrided by MicrobeWorldSimulation
    • void ProcessFrameLogic (float delta): run OnProcessFrameLogic(delta)
    • virtual void OnProcessPhysics (float delta): run WaitForStartedPhysicsRun() and OnStartPhysicsRunIfTime(delta)
      • Not overrided by MicrobeWroldSimulation
      • above call back functions are defined as abstract methods here
    • abstract void OnProcessFixedLogic (float delta)
  • class WorldSimulationWithPhysics : WorldSimulation
    • PhysicalWorld PhysicalWorld (equal to "physics")
    • List<NativePhysicsBody> createdBodies
    • override void WaitForStartedPhysicsRun (): run physics.WaitUntilPhysicsRunEnds()
    • override void OnStartPhysicsRunIfTime (float delta): run physics.ProcessPhysics(delta)
  • class partial MicrobeWorldSimulation : WorldSimulationWithPhysics
    • override void OnProcessFixedLogic (float delta): call either OnProcessFixedWithThreads or OnProcessFixedWithoutThreads defined in the separte .generated file
    • override void OnProcessFrameLogic (float delta): call OnProcessFrameLogicGenerated defined in .generated file

5. Components

Defined in the Components namespace

5.1. Common Components

5.1.1. SpatialInstance

The Godot node container

  • class SpatialInstance
    • Node3D? GraphicalInstance: the Godot node

5.1.2. Physics

Information about the motion of an entity

  • class Physics : IArchivableComponent
    • Vector3 Velocity
    • Vector3 AngularVelocity
    • NativePhysicsBody? Body
    • float? LinearDamping
    • bool

5.1.3. WorldPosition

  • class WorldPosition : IArchivableComponent
    • Vector3 Position
    • Quaternion Rotation

5.2. Microbe Components

5.2.1. MicrobeControl

The information that causes the motion of a microbe.

  • class MicrobeControl : IArchivableComponent
    • Vector3 LookAtPoint
    • Vector3 MovementDirection
    • MicrobeState State
    • bool SlowedBySlime
    • bool

6. Systems

Defined in the Systems namespace.

In src/engine/common_systems

  • PhysicsBodyCreationSystem create Jolt physics body if there is none
  • PhysicsCollisionManagementSystem manages CollisionManagement component and progapages the collision events to other systems.
  • PhysicsUpdateAndPositionSystem read physical position and rotation and store them into entity's worldPosition

6.1. Common Systems

6.1.1. SpatialAttachSystem

  • class SpatialAttachSystem : AComponentSystem<float, SpatialInstance>
    • Node godotWorldRoot: it is the visualsParent, that is, rootOfDynamicallySpawned.
    • Dictionary<Node3D, AttachedInfo> attachedSpatialInstances
    • override void Update (float state, Span<SpatialInstance components) attach only not attached components, such as microbes and minerals, to the godotWorldRoot

6.1.2. SpatialPositionSystem

Transform the graphicalInstance based on the WorldPosition of the entity

  • class SpatialPositionSystem

6.1.3. Physical World to Screen

  • class PhysicsUpdateAndPositionSystem
    • Update the WorldPosition (includes position and rotation) to the physical world position.
  • class SpatialPositionSystem
    • Transform the Godot node into the WorldPosition.

6.1.4. PhysicsBodyControlSystem

This is a fallback mechanism when we don't use physical world for the motion, or we don't use it altogether.

The velocity of Physics component is applied to the body in the physical world when VelocityApplied is set to false.

6.2. Microbe Systems

Microbe under src/microbe_stage

  • class MicrobeWorldSimulation : WorldSimulationWithPhysics
    • Node : the Godot nodes where entities are attached
    • void Init (Node visualDisplayRoot, CompoundCloudSystem cloudSystem, IMicrobeSpawnEnvironment spawnEnvironment) Set the rootOfDynamicallySpawned to the visualsParent, set up various systems that controls game mechanics.
    • various systems that control each aspect of the game mechanism
    • override void OnProcessFixedLogic (float delta): either run OnProcessFixedWithThreads(delta) or OnProcessFixedWithoutThreads(delta), which are generated in separate file.
    • override void OnProcessFrameLogic (float delta): run OnProcessFrameLogicGenerated(delta) which is generated in separate file.
    • the generated file is suffixed with .generated.cs, and the methods are included using partial class. generated methods call the Update(delta) on each system.

6.2.1. MicrobeAI

Make decision about movement and change the MicrobeControl accordingly.

6.2.2. MicrobeMovementSystem

Motion is applied to the body in physical world, based on the current WorldPosition and MicrobeControl.

The control is modified in order to generate motion.

6.2.3. MicrobeVisualsSystem

Generate the membrane into the graphicalInstance

7. UI

7.1. MainMenu

Scene: src/general/MainMenu.tscn

7.2. HUD

  • class CreatureStageHUDBase <TStage>
    • TStage? stage
    • void Init (TStage containedInStage): set stage

7.3. Input

7.3.1. Microbe

  • class PlayerMicrobeInput : NodeWithInput
    • Set the control LookAtPoint of the player to the cursor position.

8. Third Party Library

8.1. ECS

  • Entity-Component System

8.1.1. Arch

Arch.Core namespace contains the library.

World contains all entities.

  • Create, Destroy, Query

Entity is a single column in the World that represent an independent object in the game.

  • Has<T>, Add<T>, Set<T>, Get<T>, Remove<T>

Entities are grouped in 16 KB of array called chunk, and chunks with same structure are grouped in archetype. This internal structure is employed for cache optimization.

8.1.2. DefaultEcs

The ECS library used in the past

9. References

Author: Jeemin Kim

Created: 2026-09-10 Thu 21:54