engine

type Engine interface {
	common.Delegate[Engine]

	// Window returns the underlying window.
	//
	// Returns:
	//   - window.Window: the window instance
	Window() window.Window

	// EnableProfiler enables performance profiling output to the log.
	EnableProfiler()

	// DisableProfiler disables performance profiling output.
	DisableProfiler()

	// SetTickRate sets the engine tick rate in frames per second.
	// The tick callback will be called at this rate for game logic updates.
	//
	// Parameters:
	//   - fps: target frames per second (defaults to 60 if <= 0)
	SetTickRate(fps float64)

	// SetTickCallback registers the function called each engine tick.
	// Use this for game logic, physics, input processing, and animation updates.
	//
	// Parameters:
	//   - callback: function to call at the configured tick rate, receiving the delta time in seconds
	SetTickCallback(callback func(deltaTime float32))

	// SetRenderCallback registers the function called each render frame.
	// Use this for GPU buffer updates and scene rendering.
	//
	// Parameters:
	//   - callback: function to call each render frame, receiving the delta time in seconds
	SetRenderCallback(callback func(deltaTime float32))

	// SetRenderFrameLimit sets an optional render frame rate cap in frames per second.
	// Pass 0 to uncap the render loop (default).
	//
	// Parameters:
	//   - fps: maximum render frames per second (0 = uncapped)
	SetRenderFrameLimit(fps float64)

	// AddScene registers a scene at the given z-index key.
	// Scenes are rendered in ascending key order during the render loop.
	//
	// Parameters:
	//   - key: the z-index determining render order (lower renders first)
	//   - s: the Scene to register
	AddScene(key int, s scene.Scene)

	// RemoveScene removes the scene at the given z-index key.
	//
	// Parameters:
	//   - key: the z-index of the scene to remove
	RemoveScene(key int)

	// Scene retrieves the scene registered at the given z-index key.
	// Returns nil if no scene exists at that key.
	//
	// Parameters:
	//   - key: the z-index of the scene to retrieve
	//
	// Returns:
	//   - scene.Scene: the scene at the key, or nil if not found
	Scene(key int) scene.Scene

	// Scenes returns a copy of all registered scenes keyed by z-index.
	//
	// Returns:
	//   - map[int]scene.Scene: a copy of the scenes map
	Scenes() map[int]scene.Scene

	// Run starts the main engine loop (blocks until window closes).
	Run()

	// Quit signals all engine goroutines to stop and shuts down the engine.
	// This is an alternative to submitting a MessageShutdown message.
	// Safe to call multiple times; subsequent calls are no-ops.
	Quit()
}

type EngineBuilderOption func(*engine)