feat: debugger mvp

Author: rmrt1n

pkg/cardinal/cardinal.go

@@ -112,6 +112,7 @@ func NewWorld(opts WorldOptions) (*World, error) {
 
 	if *options.Debug {
 		debug := newDebugModule(world)
+		debug.control.isPaused.Store(true)
 		world.debug = &debug
 	}
 
@@ -152,19 +153,48 @@ func (w *World) run(ctx context.Context) error {
 	ticker := time.NewTicker(time.Duration(float64(time.Second) / w.options.TickRate))
 	defer ticker.Stop()
 
-	// TODO: select from debug channel to pause/play ticks.
 	for {
+		if w.debug != nil && w.debug.control.isPaused.Load() {
+			select {
+			case <-w.debug.control.resumeCh:
+				w.debug.control.isPaused.Store(false)
+			case replyCh := <-w.debug.control.stepCh:
+				if err := w.Tick(time.Now()); err != nil {
+					replyCh <- 0
+					return eris.Wrap(err, "failed to run tick during step")
+				}
+				replyCh <- w.currentTick.height
+			case replyCh := <-w.debug.control.resetCh:
+				replyCh <- w.reset()
+			case <-ctx.Done():
+				return ctx.Err()
+			}
+			continue
+		}
+
 		select {
 		case <-ticker.C:
 			if err := w.Tick(time.Now()); err != nil {
 				return eris.Wrap(err, "failed to run tick")
 			}
+		case replyCh := <-w.debug.control.pauseCh:
+			w.debug.control.isPaused.Store(true)
+			replyCh <- w.currentTick.height
 		case <-ctx.Done():
 			return ctx.Err()
 		}
 	}
 }
 
+func (w *World) reset() error {
+	w.world.Reset()
+	w.commands.Clear()
+	w.events.Clear()
+	w.currentTick.height = 0
+	w.currentTick.timestamp = time.Time{}
+	return nil
+}
+
 func (w *World) Tick(timestamp time.Time) error {
 	// TODO: commands returned to be used for debug epoch log.
 	_ = w.commands.Drain()

pkg/cardinal/debug.go

@@ -3,6 +3,7 @@ package cardinal
 import (
 	"context"
 	"net/http"
+	"sync/atomic"
 	"time"
 
 	"connectrpc.com/connect"
@@ -17,10 +18,31 @@ import (
 	"github.com/argus-labs/world-engine/proto/gen/go/worldengine/cardinal/v1/cardinalv1connect"
 )
 
+// tickControl manages pause/resume/step/reset signaling for the tick loop.
+type tickControl struct {
+	pauseCh   chan chan uint64 // Request pause, receives tick height when paused
+	resumeCh  chan struct{}    // Signal to resume
+	stepCh    chan chan uint64 // Request step, receives tick height after step
+	resetCh   chan chan error  // Request reset, receives error result
+	isPaused  atomic.Bool      // Current pause state
+	stepReady chan struct{}    // Signals that step result is ready to be read
+}
+
+func newTickControl() *tickControl {
+	return &tickControl{
+		pauseCh:   make(chan chan uint64),
+		resumeCh:  make(chan struct{}),
+		stepCh:    make(chan chan uint64),
+		resetCh:   make(chan chan error),
+		stepReady: make(chan struct{}),
+	}
+}
+
 // TODO: add tick log here.
 type debugModule struct {
 	world      *World
 	server     *http.Server
+	control    *tickControl
 	reflector  *jsonschema.Reflector
 	commands   map[string]*structpb.Struct
 	events     map[string]*structpb.Struct
@@ -30,6 +52,7 @@ type debugModule struct {
 func newDebugModule(world *World) debugModule {
 	return debugModule{
 		world:      world,
+		control:    newTickControl(),
 		commands:   make(map[string]*structpb.Struct),
 		events:     make(map[string]*structpb.Struct),
 		components: make(map[string]*structpb.Struct),
@@ -144,3 +167,88 @@ func (d *debugModule) buildTypeSchemas(cache map[string]*structpb.Struct) []*car
 	}
 	return schemas
 }
+
+// Pause stops tick execution and returns the current tick height.
+func (d *debugModule) Pause(
+	_ context.Context,
+	_ *connect.Request[cardinalv1.PauseRequest],
+) (*connect.Response[cardinalv1.PauseResponse], error) {
+	if d.control.isPaused.Load() {
+		return nil, connect.NewError(connect.CodeFailedPrecondition, eris.New("world is already paused"))
+	}
+
+	replyCh := make(chan uint64, 1)
+	d.control.pauseCh <- replyCh
+	tickHeight := <-replyCh
+
+	return connect.NewResponse(&cardinalv1.PauseResponse{
+		TickHeight: tickHeight,
+	}), nil
+}
+
+// Resume continues tick execution after a pause.
+func (d *debugModule) Resume(
+	_ context.Context,
+	_ *connect.Request[cardinalv1.ResumeRequest],
+) (*connect.Response[cardinalv1.ResumeResponse], error) {
+	if !d.control.isPaused.Load() {
+		return nil, connect.NewError(connect.CodeFailedPrecondition, eris.New("world is not paused"))
+	}
+
+	d.control.resumeCh <- struct{}{}
+
+	return connect.NewResponse(&cardinalv1.ResumeResponse{}), nil
+}
+
+// Step executes a single tick. Only works when paused.
+func (d *debugModule) Step(
+	_ context.Context,
+	_ *connect.Request[cardinalv1.StepRequest],
+) (*connect.Response[cardinalv1.StepResponse], error) {
+	if !d.control.isPaused.Load() {
+		return nil, connect.NewError(connect.CodeFailedPrecondition, eris.New("world must be paused to step"))
+	}
+
+	replyCh := make(chan uint64, 1)
+	d.control.stepCh <- replyCh
+	tickHeight := <-replyCh
+
+	return connect.NewResponse(&cardinalv1.StepResponse{
+		TickHeight: tickHeight,
+	}), nil
+}
+
+// Reset restores the world to its initial state (before tick 0).
+func (d *debugModule) Reset(
+	_ context.Context,
+	_ *connect.Request[cardinalv1.ResetRequest],
+) (*connect.Response[cardinalv1.ResetResponse], error) {
+	if !d.control.isPaused.Load() {
+		return nil, connect.NewError(connect.CodeFailedPrecondition, eris.New("world must be paused to reset"))
+	}
+
+	replyCh := make(chan error, 1)
+	d.control.resetCh <- replyCh
+	if err := <-replyCh; err != nil {
+		return nil, connect.NewError(connect.CodeInternal, err)
+	}
+
+	return connect.NewResponse(&cardinalv1.ResetResponse{}), nil
+}
+
+// GetState returns the current world state snapshot.
+func (d *debugModule) GetState(
+	_ context.Context,
+	_ *connect.Request[cardinalv1.GetStateRequest],
+) (*connect.Response[cardinalv1.GetStateResponse], error) {
+	snapshot, err := d.world.world.SerializeToProto()
+	if err != nil {
+		return nil, connect.NewError(connect.CodeInternal, eris.Wrap(err, "failed to serialize world state"))
+	}
+
+	return connect.NewResponse(&cardinalv1.GetStateResponse{
+		TickHeight: d.world.currentTick.height,
+		IsPaused:   d.control.isPaused.Load(),
+		Snapshot:   snapshot,
+	}), nil
+}

pkg/cardinal/internal/command/command.go

@@ -125,3 +125,11 @@ func (m *Manager) Drain() []Command {
 	}
 	return all
 }
+
+// Clear discards all pending commands from both queues and buffers.
+func (m *Manager) Clear() {
+	for id := range m.queues {
+		m.queues[id].Drain(&m.commands[id])
+		m.commands[id] = m.commands[id][:0]
+	}
+}

pkg/cardinal/internal/ecs/world.go

@@ -83,6 +83,11 @@ func (w *World) Serialize() ([]byte, error) {
 	return proto.MarshalOptions{Deterministic: true}.Marshal(worldState)
 }
 
+// SerializeToProto returns the World's state as a proto message.
+func (w *World) SerializeToProto() (*cardinalv1.CardinalSnapshot, error) {
+	return w.state.toProto()
+}
+
 // Deserialize populates the World's state from a byte slice.
 // This should only be called after the World has been properly initialized with components registered.
 func (w *World) Deserialize(data []byte) error {
@@ -97,3 +102,10 @@ func (w *World) Deserialize(data []byte) error {
 	w.initDone = true
 	return nil
 }
+
+// Reset clears the world state back to its initial empty state.
+// Components remain registered but all entities and archetypes are cleared.
+func (w *World) Reset() {
+	w.state.reset()
+	w.initDone = false
+}

pkg/cardinal/internal/ecs/world_state.go

@@ -48,6 +48,18 @@ func newWorldState() *worldState {
 	return &ws
 }
 
+// reset clears all entity data while preserving registered components.
+func (ws *worldState) reset() {
+	ws.mu.Lock()
+	defer ws.mu.Unlock()
+
+	ws.nextID = 0
+	ws.free = make([]EntityID, 0)
+	ws.entityArch = newSparseSet()
+	ws.archetypes = make([]*archetype, 1)
+	ws.archetypes[voidArchetypeID] = ws.newArchetype(voidArchetypeID, bitmap.Bitmap{})
+}
+
 // -------------------------------------------------------------------------------------------------
 // Entity operations
 // -------------------------------------------------------------------------------------------------

pkg/cardinal/internal/event/event.go

@@ -84,6 +84,21 @@ func (m *Manager) flush() {
 	}
 }
 
+// Clear discards all pending events from the channel and buffer.
+func (m *Manager) Clear() {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	for {
+		select {
+		case <-m.channel:
+		default:
+			m.buffer = m.buffer[:0]
+			return
+		}
+	}
+}
+
 // Dispatch loops through emitted events and calls their handler functions based on the event kind.
 // Returns all errors collected from handlers.
 func (m *Manager) Dispatch() error {

pkg/cardinal/system.go

@@ -245,7 +245,7 @@ type OtherWorld struct {
 	ShardID      string
 }
 
-// Send sends a command to an external service.
+// SendCommand sends a command to an external service.
 //
 // Example:
 //