go-ecs-tools

README

Go ECS Tools

A powerful Go library providing composition and builder patterns for Entity Component System (ECS) development using the ARK ECS framework.

Overview

This library extends the ARK ECS framework with advanced system composition capabilities, allowing you to build complex ECS applications through modular, reusable components. It provides tools for both regular systems and UI systems with flexible joining and composition patterns.

Features

• System Composition: Create composite systems from multiple smaller systems
• System Joining: Combine multiple systems with customizable execution strategies
• UI System Support: Specialized tools for UI systems with PostUpdate lifecycle
• Flexible Configuration: Extensive options for customizing system behavior
• Type Safety: Full Go type safety with interface compliance

Installation

go get github.com/zodimo/go-ecs-tools

Quick Start

Basic System Composition

import (
    "github.com/zodimo/go-ecs-tools/systems"
    "github.com/mlange-42/ark/ecs"
)

// Create a composite system
system := systems.NewCompositeSystem(
    func(w *ecs.World) {
        // Your update logic here
    },
    systems.CompositeSystemWithInitialize(func(w *ecs.World) {
        // Initialization logic
    }),
    systems.CompositeSystemWithFinalize(func(w *ecs.World) {
        // Cleanup logic
    }),
)

System Joining

// Join multiple systems together
joiner := systems.NewSystemJoiner(
    []systems.System{system1, system2, system3},
    systems.WithUpdate(func(fs ...systems.WorldFunc) systems.WorldFunc {
        return func(w *ecs.World) {
            // Custom execution strategy
            for _, f := range fs {
                f(w)
            }
        }
    }),
)

Core Packages

systems Package

The main package for regular ECS systems providing:

CompositeSystem

• Purpose: Create systems with optional initialization and finalization
• Key Functions:
  • NewCompositeSystem(update WorldFunc, opts ...CompositeOption) System
  • CompositeSystemWithInitialize(initialize WorldFunc) CompositeOption
  • CompositeSystemWithFinalize(finalize WorldFunc) CompositeOption

SystemJoiner

• Purpose: Combine multiple systems with customizable execution strategies
• Key Functions:
  • NewSystemJoiner(systems []System, opts ...Option) System
  • WithInitialize(initialize JoinWorldFuncN) Option
  • WithUpdate(update JoinWorldFuncN) Option
  • WithFinalize(finalize JoinWorldFuncN) Option

uisystems Package

Specialized package for UI systems with PostUpdate lifecycle:

CompositeUISystem

• Purpose: Create UI systems with full lifecycle control
• Key Functions:
  • NewCompositeUISystem(postUpdate WorldFunc, opts ...CompositeOption) UISystem
  • CompositeUISystemWithInitialize(initialize WorldFunc) CompositeOption
  • CompositeUISystemWithUpdate(update WorldFunc) CompositeOption
  • CompositeUISystemWithFinalize(finalize WorldFunc) CompositeOption

UISystemJoiner

• Purpose: Combine multiple UI systems with customizable execution
• Key Functions:
  • NewUISystemJoiner(systems []UISystem, opts ...JoinerOption) UISystem
  • JoinerWithInitialize(initialize JoinWorldFuncN) JoinerOption
  • JoinerWithUpdate(update JoinWorldFuncN) JoinerOption
  • JoinerWithPostUpdate(postUpdate JoinWorldFuncN) JoinerOption
  • JoinerWithFinalize(finalize JoinWorldFuncN) JoinerOption

UI System with Complete Lifecycle

uiSystem := uisystems.NewCompositeUISystem(
    func(w *ecs.World) {
        // PostUpdate - final rendering step
    },
    uisystems.CompositeUISystemWithInitialize(func(w *ecs.World) {
        // Setup UI resources
    }),
    uisystems.CompositeUISystemWithUpdate(func(w *ecs.World) {
        // Update UI state
    }),
    uisystems.CompositeUISystemWithFinalize(func(w *ecs.World) {
        // Cleanup UI resources
    }),
)

Type Definitions

Core Types

type System = app.System
type UISystem = app.UISystem
type WorldFunc = func(w *ecs.World)
type JoinWorldFuncN = func(fs ...WorldFunc) WorldFunc

System Interfaces

Both packages implement the standard ARK system interfaces:

• System: Initialize, Update, Finalize
• UISystem: InitializeUI, UpdateUI, PostUpdateUI, FinalizeUI

Dependencies

• ARK ECS v0.6.4 - Core ECS framework
• ARK Tools v0.2.1 - Additional ECS utilities

Philosophy

"The whole is greater than the sum of its parts"

This library embodies the principle of composition over inheritance, enabling you to build complex ECS systems by combining simple, focused components. Each system can be developed independently and then composed into larger, more capable systems while maintaining clean separation of concerns.

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

License

This project follows the same license as the ARK ECS framework it extends.