Documentation
¶
Overview ¶
Package coldbrew provides input management functionality for various input devices.
Package coldbrew provides a game client and scene management system for the Bappa Framework.
Coldbrew handles game lifecycle, rendering, input processing, scene transitions, and resource management. It serves as the top-level interface for game developers, coordinating between the various components of the Bappa ecosystem.
Core Concepts:
- Client: The main engine that manages game state, rendering, and input
- Scene: Isolated game worlds with their own entities, systems, and logic
- Camera: Viewports that render portions of scenes
- Systems: Components that process game logic, input, and rendering
- Receivers: Handle input from various devices (keyboard, mouse, gamepad, touch)
Basic Usage:
package main
import (
"embed"
"log"
"github.com/TheBitDrifter/blueprint"
"github.com/TheBitDrifter/coldbrew"
)
//go:embed assets/*
var assets embed.FS
func main() {
// Create a new client with resolution 640x360
// maxSpritesCached=100, maxSoundsCached=50, maxScenesCached=10
client := coldbrew.NewClient(640, 360, 100, 50, 10, assets)
// Configure the client
client.SetTitle("My Game")
client.SetWindowSize(1280, 720)
client.SetResizable(true)
// Register a scene
err := client.RegisterScene(
"MainScene", // Scene name
640, 360, // Scene dimensions
mainScenePlan, // Blueprint Plan
renderSystems, // Render systems
clientSystems, // Client systems
coreSystems, // Core systems
)
if err != nil {
log.Fatal(err)
}
// Register global systems
client.RegisterGlobalRenderSystem(rendersystems.GlobalRenderer{})
client.RegisterGlobalClientSystem(clientsystems.InputBufferSystem{})
// Setup cameras and inputs
client.ActivateCamera()
receiver, _ := client.ActivateReceiver()
// Start the game
if err := client.Start(); err != nil {
log.Fatal(err)
}
}
Coldbrew organizes systems into five categories, running in this order each frame:
- Global Client Systems: Handle input and state across all scenes
- Core Systems: Process game simulation (physics, AI, collision)
- Scene Client Systems: Process scene-specific game logic
- Global Render Systems: Handle rendering across all scenes
- Scene Render Systems: Handle rendering specific to a scene
The framework supports multiple simultaneous active scenes, enabling features like:
- Split-screen multiplayer
- UI overlays
- Level transitions
- Mini-maps and picture-in-picture views
Coldbrew uses an input abstraction layer that separates physical inputs (keyboard, mouse, gamepad) from gameplay actions, allowing for flexible control schemes and device independence.
Coldbrew is built on top of the Ebiten game engine (https://github.com/hajimehoshi/ebiten), which provides the low-level graphics rendering, input detection, and cross-platform functionality. Coldbrew extends Ebiten with a comprehensive entity-component system and game management features while integrating the other components of the Bappa Framework: Blueprint, Warehouse, Tteokbokki, and Mask.
Index ¶
- Constants
- Variables
- func IsProd() bool
- func NewSoundLoader(embeddedFS fs.FS) *soundLoader
- func NewSpriteLoader(embeddedFS fs.FS) *spriteLoader
- type CacheBustError
- type CacheResolveErrorHandler
- type Camera
- type CameraManager
- type CameraSceneRecord
- type CameraSceneTracker
- type CameraUtility
- type Client
- type ClientSystem
- type ConfigManager
- type GlobalClientSystem
- type GlobalRenderSystem
- type InputCapturer
- type InputManager
- type KeyLayout
- type LocalClient
- type LocalClientSceneManager
- type MockSoundLoader
- type MockSpriteLoader
- type MouseLayout
- type PadLayout
- type Receiver
- type RenderSystem
- type Scene
- type SceneManager
- type Screen
- func (s *Screen) Draw(target *ebiten.Image, opts *ebiten.DrawImageOptions)
- func (s *Screen) GetFrame(rowIndex, frameIndex, frameWidth, frameHeight int) *ebiten.Image
- func (s *Screen) GetTile(tileX, tileY, tileWidth, tileHeight int) *ebiten.Image
- func (s *Screen) Image() *ebiten.Image
- func (s *Screen) Name() string
- type Sound
- type SoundLoader
- type Sprite
- type SpriteLoader
- type SystemManager
- type TickManager
- type TouchLayout
Constants ¶
const MaxSplit = blueprintclient.MaxSplit
MaxSplit is the maximum number of splits allowed by the blueprint client
Variables ¶
var ClientConfig = func() *config { defConfig := config{ configWrite: configWrite{ Title: "Bappa!", DebugVisual: true, }, minimumLoadTime: 0, enforceMinOnActive: true, tps: 60, debugKey: ebiten.Key0, cameraBorderSize: 0, resolution: struct{ x, y int }{ x: 640, y: 360, }, windowSize: struct{ x, y int }{ x: 1920, y: 1080, }, } defConfig.maxSpritesCached.Store(200) defConfig.maxSoundsCached.Store(200) return &defConfig }()
Functions ¶
func NewSoundLoader ¶
NewSoundLoader creates a sound loader with 44.1kHz sample rate
func NewSpriteLoader ¶
NewSpriteLoader creates a sprite loader with the provided filesystem
Types ¶
type CacheBustError ¶
type CacheBustError struct{}
func (*CacheBustError) Error ¶
func (*CacheBustError) Error() string
type CacheResolveErrorHandler ¶
type CacheResolveErrorHandler func(error)
CacheResolveErrorHandler is a function type for handling cache resolution errors
func GetCacheResolveErrorHandler ¶
func GetCacheResolveErrorHandler() CacheResolveErrorHandler
GetCacheResolveErrorHandler safely retrieves the current error handler
func SetCacheResolveErrorHandler ¶
func SetCacheResolveErrorHandler(handler CacheResolveErrorHandler) CacheResolveErrorHandler
SetCacheResolveErrorHandler allows changing the error handler, returns the previous handler
type Camera ¶
type Camera interface {
// Ready checks if the camera is ready for rendering based on client state
Ready(Client) bool
// Active returns whether the camera is currently active
Active() bool
// Activate enables the camera
Activate()
// Deactivate clears the surface and disables the camera
Deactivate()
// Surface returns the camera's rendering surface
Surface() *ebiten.Image
// Localize transforms global scene coordinates to camera-local coordinates
Localize(pos vector.Two) vector.Two
// DrawImage renders an image at the specified scene position, localized to the camera
DrawImage(img *ebiten.Image, opts *ebiten.DrawImageOptions, pos vector.Two)
// DrawImageStatic renders an image at an absolute position without transformation (on the camera)
DrawImageStatic(img *ebiten.Image, opts *ebiten.DrawImageOptions, pos vector.Two)
// DrawTextBasic renders basic text at the specified scene position, localized to the camera
DrawTextBasic(text string, opts *text.DrawOptions, fontFace *text.GoXFace, pos vector.Two)
// DrawText renders text at the specified scene position, localized to the camera
DrawText(text string, opts *text.DrawOptions, fontFace *text.GoTextFace, pos vector.Two)
// DrawTextBasicStatic renders basic text at an absolute position (on the camera)
DrawTextBasicStatic(text string, opts *text.DrawOptions, fontFace *text.GoXFace, pos vector.Two)
// DrawTextStatic renders text at an absolute position (on the camera)
DrawTextStatic(text string, opts *text.DrawOptions, fontFace *text.GoTextFace, pos vector.Two)
// PresentToScreen renders the camera's contents to the provided screen
PresentToScreen(screen Screen, borderSize int)
// SetDimensions updates the camera's width and height
SetDimensions(width, height int)
// Dimensions returns the camera's current width and height
Dimensions() (width, height int)
// Positions returns the camera's global (screen) and local (scene/world) positions
Positions() (screen, scene *vector.Two)
// Index returns the camera's rendering priority
Index() int
// contains filtered or unexported methods
}
Camera manages viewport rendering and coordinate transformation between screen space and scene space
type CameraManager ¶
type CameraManager interface {
// CameraSceneTracker returns the tracker for camera scene transitions
CameraSceneTracker() CameraSceneTracker
// Cameras returns the array of available cameras
Cameras() [MaxSplit]Camera
// ActivateCamera attempts to activate a camera and returns it if successful
ActivateCamera() (Camera, error)
}
CameraManager handles the creation and management of camera objects and provides access to scene tracking capabilities
type CameraSceneRecord ¶
CameraSceneRecord stores information about a camera's current scene and tick
type CameraSceneTracker ¶
type CameraSceneTracker map[Camera]CameraSceneRecord
CameraSceneTracker tracks which scene each camera is rendering and when it changed
type CameraUtility ¶
type CameraUtility interface {
// ActiveCamerasFor returns all active cameras assigned to the given scene
ActiveCamerasFor(Scene) []Camera
// Ready determines if a camera is ready to be used based on timing constraints
Ready(Camera) bool
}
CameraUtility provides methods for managing camera states and retrieving active cameras for scenes
type Client ¶
type Client interface {
LocalClient
SceneManager
CameraManager
}
Client manages game state, rendering, and input
func NewClient ¶
func NewClient(baseResX, baseResY, maxSpritesCached, maxSoundsCached, maxScenesCached int, embeddedFS fs.FS) Client
NewClient creates a new client with specified resolution and cache settings
func NewTestClient ¶
func NewTestClient(baseResX, baseResY, maxSpritesCached, maxSoundsCached, maxScenesCached int) Client
NewTestClient creates a client specifically for testing purposes with mock asset loaders that don't require real files
type ClientSystem ¶
type ClientSystem interface {
Run(LocalClient, Scene) error
}
ClientSystem runs in the update loop at the scene level Processes local sound effects and input handling without access to other scenes
type ConfigManager ¶
type ConfigManager interface {
SetTitle(string)
SetWindowSize(x, y int)
SetResolution(x, y int)
SetResizable(bool)
SetFullScreen(bool)
SetMinimumLoadTime(ticks int)
SetEnforceMinOnActive(bool)
SetTPS(int)
BindDebugKey(ebiten.Key)
SetDebugMode(bool)
SetCameraBorderSize(int)
}
ConfigManager defines the interface for managing game configuration settings
type GlobalClientSystem ¶
GlobalClientSystem runs in the update loop with access to all scenes via client Typically handles sound processing and transforms raw inputs into a usable state for core simulation systems Can run before or after blueprint.CoreSystems depending on registration type
type GlobalRenderSystem ¶
GlobalRenderSystem handles rendering at the global/client level with access to all scenes
type InputCapturer ¶
type InputCapturer interface {
Capture()
}
Captures 'raw' client inputs, and passes them to the client 'receiver' for mapping/tracking
type InputManager ¶
InputManager defines the interface for managing input receivers.
type KeyLayout ¶
type KeyLayout interface {
RegisterKey(ebiten.Key, blueprint_input.Input)
}
KeyLayout maps keyboard keys to game inputs
type LocalClient ¶
type LocalClient interface {
Start() error
CameraUtility
TickManager
InputManager
CameraManager
SystemManager
ConfigManager
LocalClientSceneManager
ebiten.Game
}
type LocalClientSceneManager ¶
type MockSoundLoader ¶
type MockSoundLoader struct {
}
MockSoundLoader implements the sound loading functionality for tests
func NewMockSoundLoader ¶
func NewMockSoundLoader() *MockSoundLoader
NewMockSoundLoader creates a new MockSoundLoader
func (*MockSoundLoader) Load ¶
func (m *MockSoundLoader) Load(soundBundle *blueprintclient.SoundBundle, cache warehouse.Cache[Sound]) error
Load implements the sound loading for tests
type MockSpriteLoader ¶
type MockSpriteLoader struct{}
MockSpriteLoader implements the sprite loading functionality for tests
func NewMockSpriteLoader ¶
func NewMockSpriteLoader() *MockSpriteLoader
NewMockSpriteLoader creates a new MockSpriteLoader
func (*MockSpriteLoader) Load ¶
func (m *MockSpriteLoader) Load(spriteBundle *blueprintclient.SpriteBundle, cache warehouse.Cache[Sprite]) error
Load implements the sprite loading for tests
type MouseLayout ¶
type MouseLayout interface {
RegisterMouseButton(ebiten.MouseButton, blueprintinput.Input)
}
MouseLayout maps mouse buttons to game inputs
type PadLayout ¶
type PadLayout interface {
RegisterPad(padID int)
RegisterGamepadButton(ebiten.GamepadButton, blueprintinput.Input)
RegisterGamepadAxes(left bool, input blueprintinput.Input)
}
PadLayout manages gamepad input mapping configuration
type Receiver ¶
type Receiver interface {
RegisterPad(padID int)
Active() bool
PopInputs() []blueprint_input.StampedInput
PadLayout
KeyLayout
MouseLayout
TouchLayout
}
Receiver combines multiple input layouts and manages input state It handles keyboard, gamepad, mouse, and touch inputs
type RenderSystem ¶
type RenderSystem interface {
Render(Scene, Screen, CameraUtility)
}
RenderSystem handles rendering at the scene level and runs after global render systems when its parent scene is active
type Scene ¶
type Scene interface {
// Core information
Name() string
Height() int
Width() int
CurrentTick() int
LastSelectedTick() int
SetSelectedTick()
LastActivatedTick() int
SetActivatedTick()
TicksSinceActivated() int
TicksSinceSelected() int
// Storage and queries
Storage() warehouse.Storage
NewCursor(warehouse.QueryNode) *warehouse.Cursor
// Loading state
IsLoaded() bool
SetLoaded(bool)
IsLoading() bool
SetLoading(bool)
TryStartLoading() bool
Ready() bool
// Systems and execution
CoreSystems() []blueprint.CoreSystem
Renderers() []RenderSystem
ClientSystems() []ClientSystem
ExecutePlan() (alreadyExecuted bool, err error)
Reset() error
}
Scene manages game scene state and systems It handles loading, storage, world dimensions, and local game systems
type SceneManager ¶
type SceneManager interface {
// IsActive checks if the given scene is currently active
IsActive(Scene) bool
// LoadingScenes returns all scenes currently being loaded
LoadingScenes() []Scene
// Cache returns the scene cache
Cache() warehouse.Cache[Scene]
ActiveScenes() iter.Seq[Scene]
ActiveScene(int) Scene
SceneCount() int
// RegisterScene creates and registers a new scene with the provided configuration
RegisterScene(string, int, int, blueprint.Plan, []RenderSystem, []ClientSystem, []blueprint.CoreSystem) error
// ChangeScene transitions to a target scene, transferring specified entities
ChangeScene(target Scene, entities ...warehouse.Entity) error
// ActivateScene activates a target scene while keeping the origin scene active
ActivateScene(target Scene, entities ...warehouse.Entity) error
// DeactivateScene removes a scene from the active scenes list
DeactivateScene(target Scene)
}
SceneManager handles scene lifecycle, transitions, and state management
type Screen ¶
type Screen struct {
// contains filtered or unexported fields
}
func (*Screen) GetFrame ¶
GetFrame retrieves a frame from the sprite sheet, using the cache if available
type Sound ¶
type Sound struct {
// contains filtered or unexported fields
}
Sound represents an audio resource that can be played multiple times simultaneously
func MaterializeSound ¶
func MaterializeSound(soundBundle *blueprintclient.SoundBundle, sc blueprintclient.SoundConfig) (Sound, error)
MaterializeSound finds and returns a specific Sound object from a bundle based on the provided SoundConfig Returns an error if the sound is not found
func MaterializeSounds ¶
func MaterializeSounds(soundBundle *blueprintclient.SoundBundle) []Sound
MaterializeSounds converts a collection of sound blueprints into concrete Sound objects It skips any blueprint with an empty location key
func (Sound) GetAny ¶
GetAnyAvailable returns an available player that is not currently playing, or the first player if all are in use
func (Sound) GetAnyAvailable ¶
GetAnyAvailable returns an available player that is not currently playing,
type SoundLoader ¶
type SoundLoader interface {
Load(bundle *blueprintclient.SoundBundle, cache warehouse.Cache[Sound]) error
}
type Sprite ¶
type Sprite interface {
// Name returns the sprite's identifier
Name() string
// Image returns the underlying ebiten.Image
Image() *ebiten.Image
// Draw renders the sprite to the target image with the provided options
Draw(*ebiten.Image, *ebiten.DrawImageOptions)
// GetFrame retrieves a specific frame from a sprite sheet
GetFrame(rowIndex, frameIndex, frameWidth, frameHeight int) *ebiten.Image
// GetTile retrieves a specific tile from a tileset
GetTile(tileX, tileY, tileWidth, tileHeight int) *ebiten.Image
}
Sprite manages image state and rendering properties It contains a reference to the drawable *ebiten.Image
func MaterializeSprites ¶
func MaterializeSprites(spriteBundle *blueprintclient.SpriteBundle) []Sprite
MaterializeSprites converts a bundle of sprite blueprints into concrete Sprite objects It skips any blueprint with an empty location key
type SpriteLoader ¶
type SpriteLoader interface {
Load(spriteBundle *blueprintclient.SpriteBundle, cache warehouse.Cache[Sprite]) error
}
type SystemManager ¶
type SystemManager interface {
RegisterGlobalRenderSystem(...GlobalRenderSystem)
RegisterGlobalClientSystem(...GlobalClientSystem)
}
SystemManager manages registration of various system types
type TickManager ¶
TickManager provides game tick counting functionality and implements ebiten.Game
type TouchLayout ¶
type TouchLayout interface {
RegisterTouch(blueprintinput.Input)
}
TouchLayout maps touch input to game actions
Source Files
¶
- asset_mocker.go
- assetutil.go
- cache_error_handler.go
- camera.go
- camtracker.go
- capturer.go
- capturergamepad.go
- capturerkeyboard.go
- capturermouse.go
- capturertouch.go
- client.go
- clientasset.go
- clientcamera.go
- clientcamerautil.go
- clientinput.go
- clientregistry.go
- clientscene.go
- clienttick.go
- configread.go
- configwrite.go
- doc.go
- globalcaches.go
- isprod.go
- layoutgamepad.go
- layoutkb.go
- layoutmouse.go
- layouttouch.go
- localclientscene.go
- receiver.go
- scene.go
- screen.go
- sound.go
- soundloader.go
- sprite.go
- spriteloader.go
- systemtypes.go
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
animation
command
|
|
|
cache_bust
command
|
|
|
gamepad
command
|
|
|
keyboard
command
|
|
|
mouse
command
|
|
|
music
command
|
|
|
parallax
command
|
|
|
physicangular
command
|
|
|
physiclinear
command
|
|
|
scene_transfer
command
|
|
|
splitscreen
command
|
|
|
sprite
command
|
|
|
touch
command
|
|