system

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 1, 2026 License: LGPL-3.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodePassthrough added in v0.14.0 

func DecodePassthrough(b []byte) (map[string]any, error)

DecodePassthrough turns a command's opaque JSON passthrough bytes into the map that components and events store and that downstream systems read. Empty input yields (nil, nil). Malformed input yields a non-nil error; passthrough is best-effort forwarded data the lobby does not validate, so callers log the error and proceed with a nil map rather than failing the command.

func HeartbeatSystem 

func HeartbeatSystem(state *HeartbeatSystemState)

HeartbeatSystem processes heartbeat commands and removes stale players.

func InitSystem 

func InitSystem(state *InitSystemState)

InitSystem creates singleton index entities. Runs once at tick 0.

func LobbySystem 

func LobbySystem(state *LobbySystemState)

LobbySystem processes lobby commands.

func SetConfig 

func SetConfig(config component.ConfigComponent)

SetConfig stores the configuration for the init system to use.

func SetProvider 

func SetProvider(provider LobbyProvider)

SetProvider stores the provider for the system to use.

Types

type AssignShardCommand 

type AssignShardCommand struct {
	LobbyID   string       `json:"lobby_id"`
	RequestID string       `json:"request_id"`
	GameWorld ShardAddress `json:"game_world"`
	Reason    string       `json:"reason,omitempty"`
}

func (AssignShardCommand) FromProto added in v0.14.0 

func (c AssignShardCommand) FromProto(p *gen.AssignShardCommand) AssignShardCommand

func (AssignShardCommand) Name 

func (AssignShardCommand) Name() string

Name returns the command name.

func (AssignShardCommand) ToProto added in v0.14.0 

func (c AssignShardCommand) ToProto() *gen.AssignShardCommand

type CreateLobbyCommand 

type CreateLobbyCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
	// Preset is the label of a server-registered team configuration.
	Preset string `json:"preset"`
	// PlayerPassthroughData is opaque JSON for the creating player, forwarded to the game shard.
	PlayerPassthroughData []byte `json:"player_passthrough_data,omitempty"`
	// SessionPassthroughData is opaque JSON for the lobby session, forwarded to the game shard.
	SessionPassthroughData []byte `json:"session_passthrough_data,omitempty"`
}

CreateLobbyCommand creates a new lobby with the sender as leader. The server resolves Preset against lobby.Config.LobbyPresets and rejects unknown or empty preset labels. Clients cannot supply arbitrary team configuration; the server is the source of truth.

The target game shard is not specified here: it is assigned later by an external orchestrator via AssignShardCommand when the session starts.

func (CreateLobbyCommand) FromProto added in v0.14.0 

func (c CreateLobbyCommand) FromProto(p *gen.CreateLobbyCommand) CreateLobbyCommand

func (CreateLobbyCommand) Name 

func (CreateLobbyCommand) Name() string

Name returns the command name.

func (CreateLobbyCommand) ToProto added in v0.14.0 

func (c CreateLobbyCommand) ToProto() *gen.CreateLobbyCommand

type CreateLobbyResult 

type CreateLobbyResult struct {
	RequestID string                    `json:"request_id"`
	IsSuccess bool                      `json:"is_success"`
	Message   string                    `json:"message"`
	Lobby     component.LobbyComponent  `json:"lobby,omitempty"`
	Player    component.PlayerComponent `json:"player,omitempty"`
}

CreateLobbyResult is sent back to the client after CreateLobbyCommand.

func (CreateLobbyResult) Name 

func (r CreateLobbyResult) Name() string

Name returns the request-prefixed event name.

type DefaultProvider 

type DefaultProvider struct{}

DefaultProvider provides default implementations.

func (DefaultProvider) GenerateInviteCode 

func (DefaultProvider) GenerateInviteCode(lobby *component.LobbyComponent) string

GenerateInviteCode generates a 6-character invite code using Hash(LobbyID + Now()).

func (DefaultProvider) ValidateJoin 

func (DefaultProvider) ValidateJoin(*component.LobbyComponent, JoinLobbyCommand) (bool, string)

ValidateJoin accepts all joins by default. Games override this to enforce per-game requirements (version, region, level, etc.).

type GenerateInviteCodeCommand 

type GenerateInviteCodeCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
}

GenerateInviteCodeCommand generates a new invite code (leader only).

func (GenerateInviteCodeCommand) FromProto added in v0.14.0 

func (c GenerateInviteCodeCommand) FromProto(p *gen.GenerateInviteCodeCommand) GenerateInviteCodeCommand

func (GenerateInviteCodeCommand) Name 

func (GenerateInviteCodeCommand) Name() string

Name returns the command name.

func (GenerateInviteCodeCommand) ToProto added in v0.14.0 

func (c GenerateInviteCodeCommand) ToProto() *gen.GenerateInviteCodeCommand

type GenerateInviteCodeResult 

type GenerateInviteCodeResult struct {
	RequestID  string `json:"request_id"`
	IsSuccess  bool   `json:"is_success"`
	Message    string `json:"message"`
	InviteCode string `json:"invite_code,omitempty"`
}

GenerateInviteCodeResult is sent back to the client after GenerateInviteCodeCommand.

func (GenerateInviteCodeResult) Name 

func (r GenerateInviteCodeResult) Name() string

Name returns the request-prefixed event name.

type GetAllPlayersCommand 

type GetAllPlayersCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
}

GetAllPlayersCommand fetches all players in the caller's lobby.

func (GetAllPlayersCommand) FromProto added in v0.14.0 

func (c GetAllPlayersCommand) FromProto(p *gen.GetAllPlayersCommand) GetAllPlayersCommand

func (GetAllPlayersCommand) Name 

func (GetAllPlayersCommand) Name() string

Name returns the command name.

func (GetAllPlayersCommand) ToProto added in v0.14.0 

func (c GetAllPlayersCommand) ToProto() *gen.GetAllPlayersCommand

type GetAllPlayersResult 

type GetAllPlayersResult struct {
	RequestID string                      `json:"request_id"`
	IsSuccess bool                        `json:"is_success"`
	Message   string                      `json:"message"`
	Players   []component.PlayerComponent `json:"players,omitempty"`
}

GetAllPlayersResult is sent back to the client after GetAllPlayersCommand.

func (GetAllPlayersResult) Name 

func (r GetAllPlayersResult) Name() string

Name returns the request-prefixed event name.

type GetLobbyCommand 

type GetLobbyCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
}

GetLobbyCommand fetches the caller's current lobby snapshot. Used by reconnecting clients to restore their full view (teams, session state, assigned GameWorld, etc.) in a single round-trip.

func (GetLobbyCommand) FromProto added in v0.14.0 

func (c GetLobbyCommand) FromProto(p *gen.GetLobbyCommand) GetLobbyCommand

func (GetLobbyCommand) Name 

func (GetLobbyCommand) Name() string

Name returns the command name.

func (GetLobbyCommand) ToProto added in v0.14.0 

func (c GetLobbyCommand) ToProto() *gen.GetLobbyCommand

type GetLobbyResult 

type GetLobbyResult struct {
	RequestID string                   `json:"request_id"`
	IsSuccess bool                     `json:"is_success"`
	Message   string                   `json:"message"`
	Lobby     component.LobbyComponent `json:"lobby,omitempty"`
}

GetLobbyResult is sent back to the client after GetLobbyCommand.

func (GetLobbyResult) Name 

func (r GetLobbyResult) Name() string

Name returns the request-prefixed event name.

type GetPlayerCommand 

type GetPlayerCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
	PlayerID  string `json:"player_id"`  // Target player ID (empty = self)
}

GetPlayerCommand fetches a specific player's component data.

func (GetPlayerCommand) FromProto added in v0.14.0 

func (c GetPlayerCommand) FromProto(p *gen.GetPlayerCommand) GetPlayerCommand

func (GetPlayerCommand) Name 

func (GetPlayerCommand) Name() string

Name returns the command name.

func (GetPlayerCommand) ToProto added in v0.14.0 

func (c GetPlayerCommand) ToProto() *gen.GetPlayerCommand

type GetPlayerResult 

type GetPlayerResult struct {
	RequestID string                    `json:"request_id"`
	IsSuccess bool                      `json:"is_success"`
	Message   string                    `json:"message"`
	Player    component.PlayerComponent `json:"player,omitempty"`
}

GetPlayerResult is sent back to the client after GetPlayerCommand.

func (GetPlayerResult) Name 

func (r GetPlayerResult) Name() string

Name returns the request-prefixed event name.

type HeartbeatCommand 

type HeartbeatCommand struct {
}

HeartbeatCommand is sent periodically by clients to indicate they're still connected. Players who don't send heartbeats within the timeout period are automatically removed.

func (HeartbeatCommand) FromProto added in v0.14.0 

func (c HeartbeatCommand) FromProto(p *gen.HeartbeatCommand) HeartbeatCommand

func (HeartbeatCommand) Name 

func (HeartbeatCommand) Name() string

Name returns the command name.

func (HeartbeatCommand) ToProto added in v0.14.0 

func (c HeartbeatCommand) ToProto() *gen.HeartbeatCommand

type HeartbeatSystemState 

type HeartbeatSystemState struct {
	cardinal.BaseSystemState

	// Commands
	HeartbeatCmds cardinal.WithCommand[HeartbeatCommand]

	// Entities
	Lobbies cardinal.Contains[struct {
		Lobby cardinal.Ref[component.LobbyComponent]
	}]

	Players cardinal.Contains[struct {
		Player cardinal.Ref[component.PlayerComponent]
	}]

	LobbyIndexes cardinal.Contains[struct {
		Index cardinal.Ref[component.LobbyIndexComponent]
	}]

	Configs cardinal.Contains[struct {
		Config cardinal.Ref[component.ConfigComponent]
	}]

	// Events
	PlayerTimedOutEvents cardinal.WithEvent[PlayerTimedOutEvent]
	LeaderChangedEvents  cardinal.WithEvent[LeaderChangedEvent]
	LobbyDeletedEvents   cardinal.WithEvent[LobbyDeletedEvent]
	StartSessionResults  cardinal.WithEvent[StartSessionResult]
}

HeartbeatSystemState is the state for the heartbeat system.

type InitSystemState 

type InitSystemState struct {
	cardinal.BaseSystemState

	LobbyIndexes cardinal.Contains[struct {
		Index cardinal.Ref[component.LobbyIndexComponent]
	}]

	Configs cardinal.Contains[struct {
		Config cardinal.Ref[component.ConfigComponent]
	}]
}

InitSystemState is the state for the init system.

type InviteCodeGeneratedEvent 

type InviteCodeGeneratedEvent struct {
	LobbyID    string `json:"lobby_id"`
	InviteCode string `json:"invite_code"`
}

InviteCodeGeneratedEvent is emitted when a new invite code is generated.

func (InviteCodeGeneratedEvent) Name 

func (InviteCodeGeneratedEvent) Name() string

Name returns the event name.

type JoinLobbyCommand 

type JoinLobbyCommand struct {
	RequestID  string `json:"request_id"`        // For matching request/response
	InviteCode string `json:"invite_code"`       // Required: invite code to join
	TeamID     string `json:"team_id,omitempty"` // Optional: team to join by ID (joins first available if empty)
	// PlayerPassthroughData is opaque JSON for the joining player, forwarded to the game shard.
	PlayerPassthroughData []byte `json:"player_passthrough_data,omitempty"`
}

JoinLobbyCommand joins an existing lobby via invite code.

func (JoinLobbyCommand) FromProto added in v0.14.0 

func (c JoinLobbyCommand) FromProto(p *gen.JoinLobbyCommand) JoinLobbyCommand

func (JoinLobbyCommand) Name 

func (JoinLobbyCommand) Name() string

Name returns the command name.

func (JoinLobbyCommand) ToProto added in v0.14.0 

func (c JoinLobbyCommand) ToProto() *gen.JoinLobbyCommand

type JoinLobbyResult 

type JoinLobbyResult struct {
	RequestID   string                      `json:"request_id"`
	IsSuccess   bool                        `json:"is_success"`
	Message     string                      `json:"message"`
	Lobby       component.LobbyComponent    `json:"lobby,omitempty"`
	PlayersList []component.PlayerComponent `json:"players_list,omitempty"`
}

JoinLobbyResult is sent back to the client after JoinLobbyCommand.

func (JoinLobbyResult) Name 

func (r JoinLobbyResult) Name() string

Name returns the request-prefixed event name.

type JoinTeamCommand 

type JoinTeamCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
	TeamID    string `json:"team_id"`
}

JoinTeamCommand moves a player to a different team.

func (JoinTeamCommand) FromProto added in v0.14.0 

func (c JoinTeamCommand) FromProto(p *gen.JoinTeamCommand) JoinTeamCommand

func (JoinTeamCommand) Name 

func (JoinTeamCommand) Name() string

Name returns the command name.

func (JoinTeamCommand) ToProto added in v0.14.0 

func (c JoinTeamCommand) ToProto() *gen.JoinTeamCommand

type JoinTeamResult 

type JoinTeamResult struct {
	RequestID string                    `json:"request_id"`
	IsSuccess bool                      `json:"is_success"`
	Message   string                    `json:"message"`
	Player    component.PlayerComponent `json:"player,omitempty"`
}

JoinTeamResult is sent back to the client after JoinTeamCommand.

func (JoinTeamResult) Name 

func (r JoinTeamResult) Name() string

Name returns the request-prefixed event name.

type KickPlayerCommand 

type KickPlayerCommand struct {
	RequestID      string `json:"request_id"` // For matching request/response
	TargetPlayerID string `json:"target_player_id"`
}

KickPlayerCommand kicks a player from the lobby (leader only).

func (KickPlayerCommand) FromProto added in v0.14.0 

func (c KickPlayerCommand) FromProto(p *gen.KickPlayerCommand) KickPlayerCommand

func (KickPlayerCommand) Name 

func (KickPlayerCommand) Name() string

Name returns the command name.

func (KickPlayerCommand) ToProto added in v0.14.0 

func (c KickPlayerCommand) ToProto() *gen.KickPlayerCommand

type KickPlayerResult 

type KickPlayerResult struct {
	RequestID string `json:"request_id"`
	IsSuccess bool   `json:"is_success"`
	Message   string `json:"message"`
}

KickPlayerResult is sent back to the client after KickPlayerCommand.

func (KickPlayerResult) Name 

func (r KickPlayerResult) Name() string

Name returns the request-prefixed event name.

type LeaderChangedEvent 

type LeaderChangedEvent struct {
	LobbyID     string `json:"lobby_id"`
	OldLeaderID string `json:"old_leader_id"`
	NewLeaderID string `json:"new_leader_id"`
}

LeaderChangedEvent is emitted when leadership is transferred.

func (LeaderChangedEvent) Name 

func (LeaderChangedEvent) Name() string

Name returns the event name.

type LeaveLobbyCommand 

type LeaveLobbyCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
}

LeaveLobbyCommand leaves the current lobby.

func (LeaveLobbyCommand) FromProto added in v0.14.0 

func (c LeaveLobbyCommand) FromProto(p *gen.LeaveLobbyCommand) LeaveLobbyCommand

func (LeaveLobbyCommand) Name 

func (LeaveLobbyCommand) Name() string

Name returns the command name.

func (LeaveLobbyCommand) ToProto added in v0.14.0 

func (c LeaveLobbyCommand) ToProto() *gen.LeaveLobbyCommand

type LeaveLobbyResult 

type LeaveLobbyResult struct {
	RequestID string `json:"request_id"`
	IsSuccess bool   `json:"is_success"`
	Message   string `json:"message"`
}

LeaveLobbyResult is sent back to the client after LeaveLobbyCommand.

func (LeaveLobbyResult) Name 

func (r LeaveLobbyResult) Name() string

Name returns the request-prefixed event name.

type LobbyCreatedEvent 

type LobbyCreatedEvent struct {
	LobbyID    string `json:"lobby_id"`
	LeaderID   string `json:"leader_id"`
	InviteCode string `json:"invite_code"`
}

LobbyCreatedEvent is emitted when a lobby is created.

func (LobbyCreatedEvent) Name 

func (LobbyCreatedEvent) Name() string

Name returns the event name.

type LobbyDeletedEvent 

type LobbyDeletedEvent struct {
	LobbyID string `json:"lobby_id"`
}

LobbyDeletedEvent is emitted when a lobby is deleted.

func (LobbyDeletedEvent) Name 

func (LobbyDeletedEvent) Name() string

Name returns the event name.

type LobbyProvider 

type LobbyProvider interface {
	// GenerateInviteCode generates a custom invite code for the lobby.
	GenerateInviteCode(lobby *component.LobbyComponent) string

	// ValidateJoin runs game-specific guards on a JoinLobbyCommand after
	// the generic guards (already-in-lobby, invalid code, in-session)
	// pass and before team selection. Return ok=false with a non-empty
	// reason to reject the join; the plugin emits a JoinLobbyResult
	// failure carrying that reason. Return ok=true to allow.
	ValidateJoin(lobby *component.LobbyComponent, cmd JoinLobbyCommand) (ok bool, reason string)
}

LobbyProvider defines customizable behavior for the lobby system.

type LobbySystemState 

type LobbySystemState struct {
	cardinal.BaseSystemState

	// Commands
	CreateLobbyCmds              cardinal.WithCommand[CreateLobbyCommand]
	JoinLobbyCmds                cardinal.WithCommand[JoinLobbyCommand]
	JoinTeamCmds                 cardinal.WithCommand[JoinTeamCommand]
	LeaveLobbyCmds               cardinal.WithCommand[LeaveLobbyCommand]
	SetReadyCmds                 cardinal.WithCommand[SetReadyCommand]
	KickPlayerCmds               cardinal.WithCommand[KickPlayerCommand]
	TransferLeaderCmds           cardinal.WithCommand[TransferLeaderCommand]
	StartSessionCmds             cardinal.WithCommand[StartSessionCommand]
	NotifySessionEndCmds         cardinal.WithCommand[NotifySessionEndCommand]
	AssignShardCmds              cardinal.WithCommand[AssignShardCommand]
	GenerateInviteCodeCmds       cardinal.WithCommand[GenerateInviteCodeCommand]
	UpdateSessionPassthroughCmds cardinal.WithCommand[UpdateSessionPassthroughCommand]
	UpdatePlayerPassthroughCmds  cardinal.WithCommand[UpdatePlayerPassthroughCommand]
	GetPlayerCmds                cardinal.WithCommand[GetPlayerCommand]
	GetAllPlayersCmds            cardinal.WithCommand[GetAllPlayersCommand]
	GetLobbyCmds                 cardinal.WithCommand[GetLobbyCommand]

	// Entities
	Lobbies cardinal.Contains[struct {
		Lobby cardinal.Ref[component.LobbyComponent]
	}]

	Players cardinal.Contains[struct {
		Player cardinal.Ref[component.PlayerComponent]
	}]

	LobbyIndexes cardinal.Contains[struct {
		Index cardinal.Ref[component.LobbyIndexComponent]
	}]

	Configs cardinal.Contains[struct {
		Config cardinal.Ref[component.ConfigComponent]
	}]

	// Events (Broadcast)
	LobbyCreatedEvents              cardinal.WithEvent[LobbyCreatedEvent]
	PlayerJoinedEvents              cardinal.WithEvent[PlayerJoinedEvent]
	PlayerLeftEvents                cardinal.WithEvent[PlayerLeftEvent]
	PlayerKickedEvents              cardinal.WithEvent[PlayerKickedEvent]
	PlayerReadyEvents               cardinal.WithEvent[PlayerReadyEvent]
	PlayerChangedTeamEvents         cardinal.WithEvent[PlayerChangedTeamEvent]
	LeaderChangedEvents             cardinal.WithEvent[LeaderChangedEvent]
	SessionStartedEvents            cardinal.WithEvent[SessionStartedEvent]
	SessionAwaitingAllocationEvents cardinal.WithEvent[SessionAwaitingAllocationEvent]
	SessionEndedEvents              cardinal.WithEvent[SessionEndedEvent]
	InviteCodeGeneratedEvents       cardinal.WithEvent[InviteCodeGeneratedEvent]
	LobbyDeletedEvents              cardinal.WithEvent[LobbyDeletedEvent]
	SessionPassthroughUpdatedEvents cardinal.WithEvent[SessionPassthroughUpdatedEvent]
	PlayerPassthroughUpdatedEvents  cardinal.WithEvent[PlayerPassthroughUpdatedEvent]

	// CommandResult (request-prefixed responses)
	CreateLobbyResults              cardinal.WithEvent[CreateLobbyResult]
	JoinLobbyResults                cardinal.WithEvent[JoinLobbyResult]
	JoinTeamResults                 cardinal.WithEvent[JoinTeamResult]
	LeaveLobbyResults               cardinal.WithEvent[LeaveLobbyResult]
	SetReadyResults                 cardinal.WithEvent[SetReadyResult]
	KickPlayerResults               cardinal.WithEvent[KickPlayerResult]
	TransferLeaderResults           cardinal.WithEvent[TransferLeaderResult]
	StartSessionResults             cardinal.WithEvent[StartSessionResult]
	GenerateInviteCodeResults       cardinal.WithEvent[GenerateInviteCodeResult]
	UpdateSessionPassthroughResults cardinal.WithEvent[UpdateSessionPassthroughResult]
	UpdatePlayerPassthroughResults  cardinal.WithEvent[UpdatePlayerPassthroughResult]
	GetPlayerResults                cardinal.WithEvent[GetPlayerResult]
	GetAllPlayersResults            cardinal.WithEvent[GetAllPlayersResult]
	GetLobbyResults                 cardinal.WithEvent[GetLobbyResult]
}

LobbySystemState is the state for the lobby system.

type NotifySessionEndCommand 

type NotifySessionEndCommand struct {
	LobbyID string `json:"lobby_id"`
}

NotifySessionEndCommand is sent from game shard to lobby when session ends.

func (NotifySessionEndCommand) FromProto added in v0.14.0 

func (c NotifySessionEndCommand) FromProto(p *gen.NotifySessionEndCommand) NotifySessionEndCommand

func (NotifySessionEndCommand) Name 

func (NotifySessionEndCommand) Name() string

Name returns the command name.

func (NotifySessionEndCommand) ToProto added in v0.14.0 

func (c NotifySessionEndCommand) ToProto() *gen.NotifySessionEndCommand

type NotifySessionStartCommand 

type NotifySessionStartCommand struct {
	LobbyID    string       `json:"lobby_id"`
	LobbyWorld ShardAddress `json:"lobby_world"`
}

NotifySessionStartCommand is sent to game shard when a session starts. NotifySessionStartCommand tells the game shard a session is starting. It's a wire DTO: it carries only what the receiver needs (the lobby id and this lobby shard's address to reply to), not the live LobbyComponent/PlayerComponent — those are domain types and never go on the wire.

func (NotifySessionStartCommand) FromProto added in v0.14.0 

func (c NotifySessionStartCommand) FromProto(p *gen.NotifySessionStartCommand) NotifySessionStartCommand

func (NotifySessionStartCommand) Name 

func (NotifySessionStartCommand) Name() string

Name returns the command name.

func (NotifySessionStartCommand) ToProto added in v0.14.0 

func (c NotifySessionStartCommand) ToProto() *gen.NotifySessionStartCommand

type PlayerChangedTeamEvent 

type PlayerChangedTeamEvent struct {
	LobbyID   string                    `json:"lobby_id"`
	OldTeamID string                    `json:"old_team_id"`
	NewTeamID string                    `json:"new_team_id"`
	Player    component.PlayerComponent `json:"player"`
}

PlayerChangedTeamEvent is emitted when a player changes team.

func (PlayerChangedTeamEvent) Name 

func (PlayerChangedTeamEvent) Name() string

Name returns the event name.

type PlayerJoinedEvent 

type PlayerJoinedEvent struct {
	LobbyID string                    `json:"lobby_id"`
	TeamID  string                    `json:"team_id"`
	Player  component.PlayerComponent `json:"player"`
}

PlayerJoinedEvent is emitted when a player joins a lobby.

func (PlayerJoinedEvent) Name 

func (PlayerJoinedEvent) Name() string

Name returns the event name.

type PlayerKickedEvent 

type PlayerKickedEvent struct {
	LobbyID  string `json:"lobby_id"`
	PlayerID string `json:"player_id"`
	KickerID string `json:"kicker_id"`
}

PlayerKickedEvent is emitted when a player is kicked.

func (PlayerKickedEvent) Name 

func (PlayerKickedEvent) Name() string

Name returns the event name.

type PlayerLeftEvent 

type PlayerLeftEvent struct {
	LobbyID  string `json:"lobby_id"`
	PlayerID string `json:"player_id"`
}

PlayerLeftEvent is emitted when a player leaves a lobby.

func (PlayerLeftEvent) Name 

func (PlayerLeftEvent) Name() string

Name returns the event name.

type PlayerPassthroughUpdatedEvent 

type PlayerPassthroughUpdatedEvent struct {
	LobbyID string                    `json:"lobby_id"`
	Player  component.PlayerComponent `json:"player"`
}

PlayerPassthroughUpdatedEvent is emitted when a player's passthrough data is updated.

func (PlayerPassthroughUpdatedEvent) Name 

func (PlayerPassthroughUpdatedEvent) Name() string

Name returns the event name.

type PlayerReadyEvent 

type PlayerReadyEvent struct {
	LobbyID string                    `json:"lobby_id"`
	Player  component.PlayerComponent `json:"player"`
}

PlayerReadyEvent is emitted when a player changes ready status.

func (PlayerReadyEvent) Name 

func (PlayerReadyEvent) Name() string

Name returns the event name.

type PlayerTimedOutEvent 

type PlayerTimedOutEvent struct {
	LobbyID  string `json:"lobby_id"`
	PlayerID string `json:"player_id"`
}

PlayerTimedOutEvent is emitted when a player is removed due to missed heartbeats.

func (PlayerTimedOutEvent) Name 

func (PlayerTimedOutEvent) Name() string

Name returns the event name.

type SessionAwaitingAllocationEvent 

type SessionAwaitingAllocationEvent struct {
	LobbyID string `json:"lobby_id"`
}

SessionAwaitingAllocationEvent is emitted when a session is awaiting shard assignment. External orchestrators listen for this event and respond with an AssignShardCommand to complete the session start.

func (SessionAwaitingAllocationEvent) Name 

func (SessionAwaitingAllocationEvent) Name() string

Name returns the event name.

type SessionEndedEvent 

type SessionEndedEvent struct {
	LobbyID string `json:"lobby_id"`
}

SessionEndedEvent is emitted when a session ends.

func (SessionEndedEvent) Name 

func (SessionEndedEvent) Name() string

Name returns the event name.

type SessionPassthroughUpdatedEvent 

type SessionPassthroughUpdatedEvent struct {
	LobbyID         string         `json:"lobby_id"`
	PassthroughData map[string]any `json:"passthrough_data"`
}

SessionPassthroughUpdatedEvent is emitted when session passthrough data is updated.

func (SessionPassthroughUpdatedEvent) Name 

func (SessionPassthroughUpdatedEvent) Name() string

Name returns the event name.

type SessionStartedEvent 

type SessionStartedEvent struct {
	LobbyID   string              `json:"lobby_id"`
	GameWorld cardinal.OtherWorld `json:"game_world"`
}

SessionStartedEvent is emitted when a session starts. Carries the assigned game shard address so every player in the lobby (not just the session starter) learns which gameplay shard to connect to without a follow-up query.

func (SessionStartedEvent) Name 

func (SessionStartedEvent) Name() string

Name returns the event name.

type SetReadyCommand 

type SetReadyCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
	IsReady   bool   `json:"is_ready"`
}

SetReadyCommand sets the player's ready status.

func (SetReadyCommand) FromProto added in v0.14.0 

func (c SetReadyCommand) FromProto(p *gen.SetReadyCommand) SetReadyCommand

func (SetReadyCommand) Name 

func (SetReadyCommand) Name() string

Name returns the command name.

func (SetReadyCommand) ToProto added in v0.14.0 

func (c SetReadyCommand) ToProto() *gen.SetReadyCommand

type SetReadyResult 

type SetReadyResult struct {
	RequestID string                    `json:"request_id"`
	IsSuccess bool                      `json:"is_success"`
	Message   string                    `json:"message"`
	Player    component.PlayerComponent `json:"player,omitempty"`
}

SetReadyResult is sent back to the client after SetReadyCommand.

func (SetReadyResult) Name 

func (r SetReadyResult) Name() string

Name returns the request-prefixed event name.

type ShardAddress added in v0.14.0 

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

AssignShardCommand is sent by an external orchestrator to complete a session start that is waiting in SessionStateAwaitingAllocation. The lobby writes GameWorld directly onto the lobby component, transitions to SessionStateInSession, and dispatches NotifySessionStartCommand. The orchestrator is responsible for providing a complete GameWorld address (Region, Organization, Project, ShardID).

If GameWorld.ShardID is empty, the assignment is treated as a failure: the lobby returns to SessionStateIdle and a failure StartSessionResult is emitted with Reason as the failure message.

RequestID must equal the lobby's current Session.PendingRequestID (which the orchestrator reads from the LobbyComponent). Mismatched RequestIDs are rejected; this rejects late duplicate or stale commands that arrive after the original pending cycle has already been completed or cancelled. ShardAddress mirrors cardinal.OtherWorld for use in commands. A plugin command can't carry the core cardinal.OtherWorld directly: generating its proto in the plugin would require cardinal to import the plugin's generated package, a dependency cycle. The fields match, so the two convert directly with a Go struct conversion.

func (ShardAddress) FromProto added in v0.14.0 

func (c ShardAddress) FromProto(p *gen.ShardAddress) ShardAddress

func (ShardAddress) SendCommand added in v0.14.0 

func (a ShardAddress) SendCommand(state *cardinal.BaseSystemState, cmd cardinal.Command)

SendCommand forwards to the underlying cardinal.OtherWorld, so a command field of type ShardAddress can dispatch directly (e.g. the game shard replying to the lobby via NotifySessionStart.LobbyWorld).

func (ShardAddress) ToProto added in v0.14.0 

func (c ShardAddress) ToProto() *gen.ShardAddress

type StartSessionCommand 

type StartSessionCommand struct {
	RequestID string `json:"request_id"` // For matching request/response
}

StartSessionCommand starts the session (leader only). The corresponding StartSessionResult is emitted asynchronously, typically several ticks after this command is accepted, once an orchestrator responds with AssignShardCommand. Clients must not set short timeouts on StartSessionResult.

func (StartSessionCommand) FromProto added in v0.14.0 

func (c StartSessionCommand) FromProto(p *gen.StartSessionCommand) StartSessionCommand

func (StartSessionCommand) Name 

func (StartSessionCommand) Name() string

Name returns the command name.

func (StartSessionCommand) ToProto added in v0.14.0 

func (c StartSessionCommand) ToProto() *gen.StartSessionCommand

type StartSessionPayload 

type StartSessionPayload = NotifySessionStartCommand

StartSessionPayload is an alias for NotifySessionStartCommand for documentation clarity.

type StartSessionResult 

type StartSessionResult struct {
	RequestID string              `json:"request_id"`
	IsSuccess bool                `json:"is_success"`
	Message   string              `json:"message"`
	GameWorld cardinal.OtherWorld `json:"game_world,omitempty"`
}

StartSessionResult is sent back to the client after StartSessionCommand. Emitted asynchronously — may arrive several ticks after the command, once the orchestrator assigns a game shard via AssignShardCommand. On success, GameWorld holds the assigned shard address so the client can connect without an extra query. Zero-valued on failure.

func (StartSessionResult) Name 

func (r StartSessionResult) Name() string

Name returns the request-prefixed event name.

type TeamConfig 

type TeamConfig = component.TeamConfig

TeamConfig is an alias for component.TeamConfig to preserve the existing external type path (lobby.TeamConfig).

type TransferLeaderCommand 

type TransferLeaderCommand struct {
	RequestID      string `json:"request_id"` // For matching request/response
	TargetPlayerID string `json:"target_player_id"`
}

TransferLeaderCommand transfers leadership to another player.

func (TransferLeaderCommand) FromProto added in v0.14.0 

func (c TransferLeaderCommand) FromProto(p *gen.TransferLeaderCommand) TransferLeaderCommand

func (TransferLeaderCommand) Name 

func (TransferLeaderCommand) Name() string

Name returns the command name.

func (TransferLeaderCommand) ToProto added in v0.14.0 

func (c TransferLeaderCommand) ToProto() *gen.TransferLeaderCommand

type TransferLeaderResult 

type TransferLeaderResult struct {
	RequestID string `json:"request_id"`
	IsSuccess bool   `json:"is_success"`
	Message   string `json:"message"`
}

TransferLeaderResult is sent back to the client after TransferLeaderCommand.

func (TransferLeaderResult) Name 

func (r TransferLeaderResult) Name() string

Name returns the request-prefixed event name.

type UpdatePlayerPassthroughCommand 

type UpdatePlayerPassthroughCommand struct {
	RequestID       string `json:"request_id"` // For matching request/response
	PassthroughData []byte `json:"passthrough_data"`
}

UpdatePlayerPassthroughCommand updates the player's own passthrough data.

func (UpdatePlayerPassthroughCommand) FromProto added in v0.14.0 

func (c UpdatePlayerPassthroughCommand) FromProto(p *gen.UpdatePlayerPassthroughCommand) UpdatePlayerPassthroughCommand

func (UpdatePlayerPassthroughCommand) Name 

func (UpdatePlayerPassthroughCommand) Name() string

Name returns the command name.

func (UpdatePlayerPassthroughCommand) ToProto added in v0.14.0 

func (c UpdatePlayerPassthroughCommand) ToProto() *gen.UpdatePlayerPassthroughCommand

type UpdatePlayerPassthroughResult 

type UpdatePlayerPassthroughResult struct {
	RequestID string                    `json:"request_id"`
	IsSuccess bool                      `json:"is_success"`
	Message   string                    `json:"message"`
	Player    component.PlayerComponent `json:"player,omitempty"`
}

UpdatePlayerPassthroughResult is sent back to the client after UpdatePlayerPassthroughCommand.

func (UpdatePlayerPassthroughResult) Name 

func (r UpdatePlayerPassthroughResult) Name() string

Name returns the request-prefixed event name.

type UpdateSessionPassthroughCommand 

type UpdateSessionPassthroughCommand struct {
	RequestID       string `json:"request_id"` // For matching request/response
	PassthroughData []byte `json:"passthrough_data"`
}

UpdateSessionPassthroughCommand updates the session passthrough data (leader only).

func (UpdateSessionPassthroughCommand) FromProto added in v0.14.0 

func (c UpdateSessionPassthroughCommand) FromProto(p *gen.UpdateSessionPassthroughCommand) UpdateSessionPassthroughCommand

func (UpdateSessionPassthroughCommand) Name 

func (UpdateSessionPassthroughCommand) Name() string

Name returns the command name.

func (UpdateSessionPassthroughCommand) ToProto added in v0.14.0 

func (c UpdateSessionPassthroughCommand) ToProto() *gen.UpdateSessionPassthroughCommand

type UpdateSessionPassthroughResult 

type UpdateSessionPassthroughResult struct {
	RequestID string `json:"request_id"`
	IsSuccess bool   `json:"is_success"`
	Message   string `json:"message"`
}

UpdateSessionPassthroughResult is sent back to the client after UpdateSessionPassthroughCommand.

func (UpdateSessionPassthroughResult) Name 

func (r UpdateSessionPassthroughResult) Name() string

Name returns the request-prefixed event name.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.