Docs
Getting Started
Updates
GitHub
search
homechevron_rightOopchevron_rightGame state machine

Game State Machine

The game state system uses a scoreboard to track the current state and dispatches handlers when the state matches.

It is a good fit for lobbies, round systems, multi-phase boss fights, tutorials, or any flow that repeatedly switches between a known set of named states.

Registering states

val states = registerGameStates {
	state("lobby")
	state("playing")
	state("ended")
}
Kotlin

This generates a load function that creates the kore_state objective and sets the initial state.

Typical lifecycle

function("prepare_game") {
	states.transitionTo("lobby")
}

function("start_game") {
	states.transitionTo("playing")
}

function("finish_game") {
	states.transitionTo("ended")
}
Kotlin

Keeping transitions explicit like this makes it easier to reason about which setup code belongs to each phase.

Transitioning and reacting

function("game_loop") {
	states.transitionTo("playing")

	states.whenState("playing") {
		say("The game is in progress!")
	}

	states.whenState("ended") {
		say("Game over!")
	}
}
Kotlin

Game state actions

Helper functions integrate states with other OOP systems:

// Transition to a state only when a cooldown is ready
states.transitionWithCooldown("playing", cooldown, player)

// Spawn entities when entering a state
states.whenStateSpawn("playing", zombieSpawner, count = 3)

// Start a timer when entering a state
states.whenStateStartTimer("playing", timer, player)
Kotlin

Best practices

  • Keep the state list small and meaningful (lobby, playing, ended, etc.).
  • Reserve whenState(...) for behavior that should only run in one phase.
  • Use the integration helpers when a state change should also start a timer, consume a cooldown, or trigger a spawn.
Published03/03/2026Last updated31/03/2026
Edit this page on GitHub
← PreviousEventsNext →Items