Class WorldBuilder

Namespace

KeenEyes

Assembly

KeenEyes.Core.dll

Fluent builder for configuring and creating independent World instances.

public sealed class WorldBuilder

Inheritance

object

WorldBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Create a reusable builder
var builder = new WorldBuilder()
    .WithSystem<MovementSystem>(SystemPhase.Update)
    .WithSystem<PhysicsSystem>(SystemPhase.FixedUpdate);

// Create independent worlds
var clientWorld = builder.Build();
clientWorld.Name = "Client";

var serverWorld = builder.Build();
serverWorld.Name = "Server";

// Completely isolated - different component IDs, entity IDs, system instances

Remarks

WorldBuilder enables creating multiple worlds with the same configuration. Each call to Build() creates a completely independent world instance with its own component registry, entity pool, and system instances.

This is useful for:

• Client-server simulations (separate worlds for client and server)
• Test isolation (each test gets a fresh world)
• Multi-scene games (separate worlds for menu, gameplay, etc.)

The builder pattern allows for fluent chaining of configuration options, making the setup code readable and self-documenting.

Methods

Build()

Builds and returns a new configured World instance.

public World Build()

Returns

World

A new world with all configured plugins and systems.

Examples

var world = new WorldBuilder()
    .WithPlugin<PhysicsPlugin>()
    .WithSystem<GameplaySystem>()
    .Build();

// Use the world
world.Update(deltaTime);

Remarks

The build process:

1. Creates a new World instance
2. Installs all plugins in the order they were added
3. Registers all systems in the order they were added

After calling Build(), the builder can be reused to create additional world instances with the same configuration, provided it holds only generic/factory registrations. A builder that holds system instances (added via WithSystem(ISystem, SystemPhase, int) or WithSystemGroup(SystemGroup, SystemPhase, int)) can build only once; a second call throws InvalidOperationException.

Exceptions

InvalidOperationException

Thrown when the builder holds system instances and Build() has already been called, since reusing a shared system instance would corrupt the previously built world.

WithPlugin(IWorldPlugin)

Adds a plugin instance to be installed when the world is built.

public WorldBuilder WithPlugin(IWorldPlugin plugin)

Parameters

plugin IWorldPlugin

The plugin instance to install.

Returns

WorldBuilder

This builder for method chaining.

Examples

var physics = new PhysicsPlugin(gravity: -9.81f);
var world = new WorldBuilder()
    .WithPlugin(physics)
    .Build();

Remarks

Use this overload when you need to pass a pre-configured plugin instance.

Note: When using a plugin instance, the same instance will be used if Build() is called multiple times. For independent worlds, use the generic WithPlugin<T>() method or create new WorldBuilder instances.

WithPlugin<T>()

Adds a plugin to be installed when the world is built.

public WorldBuilder WithPlugin<T>() where T : IWorldPlugin, new()

Returns

WorldBuilder

This builder for method chaining.

Type Parameters

T

The plugin type to install.

Examples

var world = new WorldBuilder()
    .WithPlugin<CorePlugin>()
    .WithPlugin<PhysicsPlugin>()
    .Build();

Remarks

Plugins are installed in the order they are added. This allows plugins to depend on other plugins that were added earlier.

A new plugin instance is created for each call to Build(), allowing the builder to be reused for multiple worlds.

WithSystem(ISystem, SystemPhase, int)

Adds a system instance to be registered when the world is built.

public WorldBuilder WithSystem(ISystem system, SystemPhase phase = SystemPhase.Update, int order = 0)

Parameters

system ISystem

The system instance to register.

phase SystemPhase

The execution phase for this system. Defaults to Update.

order int

The execution order within the phase. Lower values execute first. Defaults to 0.

Returns

WorldBuilder

This builder for method chaining.

Remarks

Use this overload when you need to pass a pre-configured system instance.

Because the same instance is shared, a builder holding a system instance can only build a single world; calling Build() a second time throws InvalidOperationException rather than rebind the instance to a new world. Use the generic WithSystem<T>(SystemPhase, int) overload for reusable builders.

WithSystem(ISystem, SystemPhase, int, Type[], Type[])

Adds a system instance to be registered when the world is built with dependency constraints.

public WorldBuilder WithSystem(ISystem system, SystemPhase phase, int order, Type[] runsBefore, Type[] runsAfter)

Parameters

system ISystem

The system instance to register.

phase SystemPhase

The execution phase for this system.

order int

The execution order within the phase. Lower values execute first.

runsBefore Type[]

Types of systems that this system must run before.

runsAfter Type[]

Types of systems that this system must run after.

Returns

WorldBuilder

This builder for method chaining.

WithSystemGroup(SystemGroup, SystemPhase, int)

Adds a system group to be registered when the world is built.

public WorldBuilder WithSystemGroup(SystemGroup group, SystemPhase phase = SystemPhase.Update, int order = 0)

Parameters

group SystemGroup

The system group to register.

phase SystemPhase

The execution phase for this group. Defaults to Update.

order int

The execution order within the phase. Lower values execute first. Defaults to 0.

Returns

WorldBuilder

This builder for method chaining.

Examples

var gameplayGroup = new SystemGroup("Gameplay")
    .Add<InputSystem>(order: 0)
    .Add<MovementSystem>(order: 10);

var world = new WorldBuilder()
    .WithSystemGroup(gameplayGroup, SystemPhase.Update)
    .Build();

Remarks

Because the group and its systems are shared instances, a builder holding a system group can only build a single world; calling Build() a second time throws InvalidOperationException rather than rebind the shared systems to a new world.

WithSystem<T>(SystemPhase, int)

Adds a system to be registered when the world is built.

public WorldBuilder WithSystem<T>(SystemPhase phase = SystemPhase.Update, int order = 0) where T : ISystem, new()

Parameters

phase SystemPhase

The execution phase for this system. Defaults to Update.

order int

The execution order within the phase. Lower values execute first. Defaults to 0.

Returns

WorldBuilder

This builder for method chaining.

Type Parameters

T

The system type to register.

Examples

var world = new WorldBuilder()
    .WithPlugin<PhysicsPlugin>()
    .WithSystem<MovementSystem>(SystemPhase.Update, order: 0)
    .WithSystem<RenderSystem>(SystemPhase.Render)
    .Build();

Remarks

Systems added through the builder are registered after all plugins are installed. This allows systems to depend on plugin-provided functionality.

WithSystem<T>(SystemPhase, int, Type[], Type[])

Adds a system to be registered when the world is built with dependency constraints.

public WorldBuilder WithSystem<T>(SystemPhase phase, int order, Type[] runsBefore, Type[] runsAfter) where T : ISystem, new()

Parameters

phase SystemPhase

The execution phase for this system.

order int

The execution order within the phase. Lower values execute first.

runsBefore Type[]

Types of systems that this system must run before.

runsAfter Type[]

Types of systems that this system must run after.

Returns

WorldBuilder

This builder for method chaining.

Type Parameters

T

The system type to register.