cardinal

type BaseCommand ¶

type BaseCommand struct{}

BaseCommand is a base command type that all commands should embed.

type BaseEvent ¶

type BaseEvent struct{}

BaseEvent is a base event type that all events should embed.

type BaseSystemState ¶

type BaseSystemState struct {
	ecs.BaseSystemState
	// contains filtered or unexported fields
}

BaseSystemState provides common functionality for system state types. It should be embedded in your system state types to allow your systems to access the world state.

Example:

// Define your system state by embedding BaseState.
type DebugSystemState struct {
    cardinal.BaseSystemState
    // Other fields...
}

// Your system function receives a pointer to your system state.
func DebugSystem(state *DebugSystemState) error {
    state.Logger().Debug().Int("tick", state.Tick()).Msg("...")
    return nil
}

func (b *BaseSystemState) Logger() *zerolog.Logger

func (b *BaseSystemState) Tick() uint64

func (b *BaseSystemState) Timestamp() time.Time

type Contains ¶

type Contains[T any] = ecs.Contains[T]

ECS type aliases for easier user imports.

type Exact ¶

type Exact[T any] = ecs.Exact[T]

ECS type aliases for easier user imports.

type OtherWorld ¶

type OtherWorld struct {
	Region       string
	Organization string
	Project      string
	ShardID      string
}

OtherWorld is a type that represents the address of an external service.

func (o OtherWorld) Send(state *BaseSystemState, command ecs.Command)

func GameSystem(state *GameSystem) error {
  MatchmakingService.Send(state, &external.EndGameCommand{
    Winner: "Team 1",
  })
}

type Ref ¶

type Ref[T ecs.Component] = ecs.Ref[T]

ECS type aliases for easier user imports.

type WithCommand ¶

type WithCommand[T ecs.Command] struct {
	ecs.WithCommand[T]
}

WithCommand is a generic system state field that allows systems to receive commands of type T during each tick. Commands must embed a cardinal.BaseCommand that provides common methods for commands. The commands are automatically registered when the systems are registered.

Example:

// Define a command type for spawning players.
type SpawnPlayerCommand struct {
    cardinal.BaseCommand
    Name string
}

func (SpawnPlayerCommand) Name() string { return "spawn-player" }

// Define your system state.
type SpawnSystemState struct {
    cardinal.BaseSystemState
    SpawnPlayerCommands cardinal.WithCommand[SpawnPlayerCommand]
    // Other fields...
}

// Your system function receives a pointer to your system state.
func SpawnSystem(state *SpawnSystemState) error {
    // Process all spawn commands for the current tick.
    for command := range state.SpawnPlayerCommands.Iter() {
        state.Players.Create(PlayerTag{Name: command.Name}, Health{Value: 100})
    }
    return nil
}

type WithEvent ¶

type WithEvent[T ecs.Event] struct {
	ecs.WithEvent[T]
}

WithEvent is a generic system state field that allows systems to emit events of type T. Events must embed a cardinal.BaseEvent that provides common methods for events. At the end of each tick, events are published to their respective subjects.

Example:

// Define an event type for player deaths.
type LevelUpEvent struct {
    cardinal.BaseEvent
    Nickname string
}

func (LevelUpEvent) Name() string { return "level-up" }

type LevelUpSystemState struct {
    cardinal.BaseSystemState
    LevelUpEvents cardinal.WithEvent[LevelUpEvent]
    // Other fields...
}

// Emit a level up event from one system.
func LevelUpSystem(state *LevelUpSystemState) error {
    state.LevelUpEvents.Emit(LevelUpEvent{Nickname: "Player1"})
    return nil
}

type WithSystemEventEmitter ¶

type WithSystemEventEmitter[T ecs.SystemEvent] struct {
	ecs.WithSystemEventEmitter[T]
}

WithSystemEventEmitter is a generic system state field that allows systems to emit system events of type T. System events don't have to be registered, and can be used to communicate between systems.

Example:

// Define a system event for player deaths.
type PlayerDeathEvent struct { Nickname string }

func (PlayerDeathEvent) Name() string { return "player-death" }

type CombatSystemState struct {
    PlayerDeathEvents ecs.WithSystemEventEmitter[PlayerDeathEvent]
    // Other fields...
}

// Emit a player death event from one system.
func CombatSystem(state *CombatSystemState) error {
    state.PlayerDeathEvents.Emit(PlayerDeathEvent{Nickname: "Player1"})
    return nil
}

type WithSystemEventReceiver ¶

type WithSystemEventReceiver[T ecs.SystemEvent] struct {
	ecs.WithSystemEventReceiver[T]
}

WithSystemEventReceiver is a generic system state field that allows systems to receive system events of type T. System events don't have to be registered, and can be used to communicate between systems.

Example:

// Define a system event for player deaths.
type PlayerDeathEvent struct { Nickname string }

func (PlayerDeathEvent) Name() string { return "player-death" }

type GraveyardSystemState struct {
    cardinal.BaseSystemState
    PlayerDeathEvents cardinal.WithSystemEventReceiver[PlayerDeathEvent]
    // Other fields...
}

// Receive a player death event from another system.
func GraveyardSystem(state *GraveyardSystemState) error {
    for event := range state.PlayerDeathEvents.Iter() {
        state.Logger().Info().Msgf("Player %s died", event.Nickname)
    }
    return nil
}

type World ¶

type World struct {
	*micro.Shard // Embedded base shard functionalities
	// contains filtered or unexported fields
}

World represents your game world and serves as the main entry point for Cardinal.

func NewWorld(opts WorldOptions) (*World, error)

func (w *World) StartGame()

type WorldOptions ¶

type WorldOptions struct {
	Region                 string                       // Region the shard is deployed to
	Organization           string                       // The organization that owns this world
	Project                string                       // Name of the project within the organization
	ShardID                string                       // Unique ID for of world's instance
	PrivateKey             string                       // Hex-encoded Ed25519 private key for signing commands
	PersonaFilePath        string                       // Path to persist the persona ID file
	EpochFrequency         uint32                       // Number of ticks per epoch
	TickRate               float64                      // Number of ticks per second
	SnapshotStorageType    micro.SnapshotStorageType    // Snapshot storage type
	SnapshotStorageOptions micro.SnapshotStorageOptions // Optional snapshot storage options
}