Core namespace for the libultraship engine framework. More...

Namespaces
namespace	Math
	Lightweight math utility functions used throughout the engine.

namespace	Scripting

Classes
class	Action
	Represents a discrete, repeatable operation run by a Tickable. More...

class	ActionList
	Generic ordered container of `Action` instances. More...

class	Archive
	Abstract base class representing a mounted archive (OTR, O2R, or folder). More...

class	ArchiveManager
	Manages a prioritised collection of mounted Archive objects. More...

struct	ArchiveManifest
	Metadata block embedded in an archive's manifest file. More...

class	Audio
	Manages audio playback through a platform-specific AudioPlayer. More...

class	AudioPlayer
	Abstract base class for platform-specific audio output backends. More...

struct	AudioSettings
	Configuration parameters shared by all AudioPlayer backends. More...

class	AxisDirectionMappingFactory
	Factory for creating ControllerAxisDirectionMapping instances. More...

class	BasicComponentList
	Extends PartList<Component, StoredPtr> with name- and type-based search helpers. More...

class	BinaryReader
	Sequential binary reader with configurable byte-order support.

class	BinaryWriter
	Sequential binary writer with configurable byte-order support. More...

class	Blob
	Resource type representing a generic binary blob. More...

class	ButtonMappingFactory
	Factory for creating ControllerButtonMapping instances. More...

struct	CommandArgument
	Metadata for a single positional argument of a console command. More...

struct	CommandEntry
	Registration record for a single console command. More...

class	Component
	A named Part with a parent/child hierarchy and optional thread safety. More...

class	ComponentHierarchyWindow
	A GuiWindow that displays the Component hierarchy tree and the list of TickableComponents registered with the Context. More...

class	Config
	Persistent JSON-backed key-value configuration store. More...

class	ConfigVersionUpdater
	Abstract class representing a Config Version Updater, intended to express how to upgrade a Configuration file from one version of a config to another (i.e. removing default values, changing option names, etc.) It can be used by subclassing `ConfigVersionUpdater`, implementing the Update function, and implementing the Constructor passing the version that the Config is being updated to to this class' constructor from the child class' default constructor. For example: More...

class	ConnectedPhysicalDeviceManager
	Tracks connected SDL game controllers and manages per-port ignore lists. More...

class	Console
	In-process command interpreter used by ConsoleWindow. More...

class	ConsoleVariable
	Manages a named collection of console variables (CVars). More...

class	ConsoleWindow
	An ImGui window that provides an in-game developer console. More...

class	Context
	Central singleton context for the libultraship engine. More...

class	ControlDeck
	Manages all controller ports and routes input/blocking requests. More...

class	ControlDevice
	Abstract base class for all input devices that can be connected to a ControlPort. More...

class	Controller
	Represents a single logical controller connected to a ControlPort. More...

class	ControllerAxisDirectionMapping
	Maps a physical input to a virtual analog stick direction. More...

class	ControllerButton
	Aggregates all ControllerButtonMapping instances for a single logical button. More...

class	ControllerButtonMapping
	Maps a physical input to a virtual controller button. More...

class	ControllerDefaultMappings
	Holds the default input-to-button and input-to-axis mappings for a controller. More...

class	ControllerGyro
	Manages the single gyroscope (motion sensor) mapping for a controller port. More...

class	ControllerGyroMapping
	Maps a physical gyroscope to virtual gyro input values. More...

class	ControllerInputMapping
	Base class for controller mappings that represent a physical input. More...

class	ControllerLED
	Aggregates LED output mappings and drives controller lighting hardware. More...

class	ControllerLEDMapping
	Maps LED colour output to a physical controller. More...

class	ControllerMapping
	Base class for all controller mappings. More...

class	ControllerRumble
	Aggregates rumble output mappings and drives force-feedback hardware. More...

class	ControllerRumbleMapping
	Maps rumble (haptic feedback) output to a physical controller. More...

class	ControllerStick
	Aggregates axis-direction mappings and applies sensitivity, dead-zone, and notch-snap to a stick. More...

class	ControlPort
	Represents a single physical controller port on the console. More...

struct	Coords
	Identifies the graphics/windowing backend in use. More...

struct	CoordsF
	Floating-point pixel coordinates. More...

class	CoreAudioAudioPlayer
	AudioPlayer implementation backed by Apple's Core Audio framework. More...

class	CrashHandler
	Installs platform-specific signal / exception handlers to capture crash information. More...

struct	CVar
	A single console variable (CVar) holding a typed value. More...

class	EventAction
	Action specialization for event-driven dispatch. More...

class	EventActionList
	ActionList specialization with indexed EventAction lookup by EventID. More...

class	EventDebuggerWindow
	An ImGui window for inspecting and debugging engine events at runtime. More...

struct	EventRegistration
	Tracks registration state for a single EventID. More...

class	Events
	Tickable event bus that dispatches listeners through `Tick(EventID)`. More...

struct	File
	Raw file buffer as read from an archive or the filesystem. More...

class	FileDrop
	Handles drag-and-drop file events for the application window. More...

class	FileHelper
	Utility class providing static helpers for reading and writing files on disk. More...

class	FolderArchive
	Archive implementation backed by an on-disk directory tree. More...

class	FolderManager
	Thin Objective-C++ bridge for locating macOS standard directories. More...

class	Font
	A resource representing a loaded font file (e.g. TTF). More...

class	GameOverlay
	Renders on-screen timed notification messages. More...

class	GlobalSDLDeviceSettings
	Global threshold settings for SDL gamepad analog axes. More...

class	Gui
	Owns and drives the ImGui context, all registered GuiWindows, and texture management. More...

class	GuiElement
	Abstract base class for all visible GUI elements (windows, menu bars, overlays). More...

class	GuiMenuBar
	The application's main ImGui menu bar rendered at the top of the screen. More...

class	GuiTexture
	A resource representing a texture intended for use in the GUI (ImGui). More...

struct	GuiTextureMetadata
	Metadata describing a GUI texture after it has been uploaded to the renderer. More...

class	GuiWindow
	A floating ImGui window managed by the Ship Gui layer. More...

class	GyroMappingFactory
	Factory for creating ControllerGyroMapping instances. More...

class	HResultException
	Exception type for failed Windows HRESULT values. More...

class	IResource
	Non-templated base interface for all resources managed by the ResourceManager. More...

class	Json
	Resource type representing a parsed JSON document. More...

class	KeyboardKeyToAnyMapping
	Base class for mappings that bind a keyboard key to any controller input. More...

class	KeyboardKeyToAxisDirectionMapping
	Maps a keyboard key to a virtual analog stick direction. More...

class	KeyboardKeyToButtonMapping
	Maps a keyboard key to a virtual controller button. More...

class	Keystore
	Persistent store of cryptographic keys used for archive signature verification. More...

struct	KeystoreEntry
	A single named key stored in the Keystore. More...

class	LEDMappingFactory
	Factory for creating ControllerLEDMapping instances. More...

class	ListenerAction
	Event-bus listener action executed by `Events::Tick(EventID)`. More...

class	Logger
	Component wrapper around an spdlog::logger instance. More...

class	MemoryStream
	A Stream backed by an in-memory byte buffer. More...

class	Mobile

class	MouseButtonToAnyMapping
	Base class for mappings that bind a mouse button to any controller input. More...

class	MouseButtonToAxisDirectionMapping
	Maps a mouse button to a virtual analog stick direction. More...

class	MouseButtonToButtonMapping
	Maps a mouse button to a virtual controller button. More...

class	MouseStateManager
	Manages mouse capture and cursor visibility state for the application window. More...

class	MouseWheelToAnyMapping
	Base class for mappings that bind a mouse scroll-wheel direction to any controller input. More...

class	MouseWheelToAxisDirectionMapping
	Maps a mouse scroll-wheel direction to a virtual analog stick direction. More...

class	MouseWheelToButtonMapping
	Maps a mouse scroll-wheel direction to a virtual controller button. More...

class	NullAudioPlayer
	A no-op AudioPlayer used when no audio device is available or audio is disabled. More...

class	O2rArchive
	Archive implementation backed by a ZIP file (.o2r format). More...

class	OtrArchive
	Archive implementation backed by an MPQ file (Blizzard's MoPaQ format). More...

struct	Overlay
	An active overlay item managed by GameOverlay. More...

class	Part
	Base class for all identifiable objects in the component system. More...

class	PartList
	A thread-safe ordered list of Parts. More...

struct	PartListStoredPtrTraits

struct	PartListStoredPtrTraits< C, std::shared_ptr< C > >
	Pointer-traits adapter for strong storage (`std::shared_ptr`). More...

struct	PartListStoredPtrTraits< C, std::weak_ptr< C > >
	Pointer-traits adapter for weak storage (`std::weak_ptr`). More...

class	PathHelper
	Utility class providing static helpers for extracting components from filesystem paths. More...

class	Resource
	Typed resource base class that provides a strongly-typed pointer accessor. More...

class	ResourceFactory
	Abstract factory interface for deserializing a specific resource type and format. More...

class	ResourceFactoryBinary
	ResourceFactory specialization for binary-format resource files. More...

class	ResourceFactoryBinaryBlobV0
	Binary factory for Blob resources (version 0). More...

class	ResourceFactoryBinaryFontV0
	Factory for deserializing version-0 binary Font resources from archive files. More...

class	ResourceFactoryBinaryGuiTextureV0
	Factory for deserializing version-0 binary GuiTexture resources from archive files. More...

class	ResourceFactoryBinaryJsonV0
	Binary factory for Json resources (version 0). More...

class	ResourceFactoryBinaryShaderV0
	Binary factory for Shader resources (version 0). More...

struct	ResourceFactoryKey
	Cache key that uniquely identifies a ResourceFactory by format, type, and version. More...

struct	ResourceFactoryKeyHash
	std::hash specialization for ResourceFactoryKey, used by the factory map. More...

class	ResourceFactoryXML
	ResourceFactory specialization for XML-format resource files. More...

struct	ResourceFilter
	Specifies which resources to include or exclude when performing a bulk load/unload. More...

class	ResourceIdentifier
	Uniquely identifies a cached resource by path/hash, owner, and source archive. More...

struct	ResourceIdentifierHash
	std::hash specialization for ResourceIdentifier, used by unordered containers. More...

struct	ResourceInitData
	Metadata that describes how a resource was (or should be) loaded. More...

class	ResourceLoader
	Parses raw file data into IResource objects using registered ResourceFactory instances. More...

class	ResourceManager
	Central manager for loading, caching, and unloading game resources. More...

class	RumbleMappingFactory
	Factory for creating ControllerRumbleMapping instances. More...

class	ScriptLoader
	Manages compilation, loading, and lifetime of runtime scripts. More...

class	SDLAddRemoveDeviceEventHandler
	Hidden GuiWindow that listens for SDL controller add/remove events. More...

class	SDLAudioPlayer
	AudioPlayer implementation backed by SDL2's audio subsystem. More...

class	SDLAxisDirectionToAnyMapping
	Base class for mappings that bind an SDL gamepad axis direction to any controller input. More...

class	SDLAxisDirectionToAxisDirectionMapping
	Maps an SDL gamepad axis direction to a virtual analog stick direction. More...

class	SDLAxisDirectionToButtonMapping
	Maps an SDL gamepad axis direction to a virtual controller button. More...

class	SDLButtonToAnyMapping
	Base class for mappings that bind an SDL gamepad button to any controller input. More...

class	SDLButtonToAxisDirectionMapping
	Maps an SDL gamepad button to a virtual analog stick direction. More...

class	SDLButtonToButtonMapping
	Maps an SDL gamepad button to a virtual controller button. More...

class	SDLGyroMapping
	Maps an SDL gamepad's gyroscope sensor to a virtual gyro input. More...

class	SDLLEDMapping
	Maps an SDL gamepad's LED to a controller LED output. More...

class	SDLRumbleMapping
	Maps an SDL gamepad's haptic motors to a controller rumble output. More...

class	Shader
	Resource type representing a shader program source. More...

class	SoundMatrixDecoder

class	StatsWindow
	An ImGui window that displays runtime performance statistics. More...

class	Stream
	Abstract base class for sequential byte streams (read/write). More...

class	ThreadPool
	Component wrapper around a BS::thread_pool. More...

class	Tickable
	Manages a collection of Actions and indexed EventActions. More...

class	TickableComponent
	Combines Tickable and Component, auto-registering with a Context. More...

class	TickableList
	Extends PartList<TickableComponent> with order-aware sorting. More...

class	WasapiAudioPlayer
	AudioPlayer implementation backed by the Windows Audio Session API (WASAPI). More...

struct	WheelDirections
	Holds the current horizontal and vertical scroll-wheel directions. More...

class	WheelHandler
	Tracks mouse scroll-wheel state and converts it into axis-like values consumable by the input mapping system. More...

class	Window
	Abstract base class for the application window and rendering surface. More...

struct	WindowRect
	Screen-space rectangle in integer pixels. More...

Typedefs
using	EventActionCppCallback = std::function< bool(EventID, uintptr_t)>
	C++ callback signature for EventAction dispatch.

using	EventActionRawCallback = bool(*)(EventID, uintptr_t)
	C-style callback signature for EventAction dispatch.

using	EventActionCallback = std::variant< std::monostate, EventActionCppCallback, uintptr_t >
	Stored callback target for EventAction.

typedef enum Ship::ConsoleVariableType	ConsoleVariableType
	Discriminator tag for the active field of the CVar union.

typedef struct Ship::CVar	CVar
	A single console variable (CVar) holding a typed value.

typedef enum Ship::KbEventType	KbEventType
	Identifies the type of a keyboard event delivered to the input mapping system.

typedef enum Ship::KbScancode	KbScancode
	Platform-independent keyboard scan codes used by the input mapping system.

typedef enum Ship::MouseBtn	MouseBtn
	Identifies a mouse button delivered to the input mapping system.

typedef enum Ship::WheelDirection	WheelDirection
	Identifies a scroll-wheel direction delivered to the input mapping system.

using	ComponentList = BasicComponentList< std::shared_ptr< Component > >
	Owning child-component list storage type.

using	ParentComponentList = BasicComponentList< std::weak_ptr< Component > >
	Non-owning parent-component list storage type.

typedef std::function< int32_t(std::shared_ptr< Console > console, std::vector< std::string > args, std::string *output)>	CommandHandler
	Signature of a function that handles a console command.

typedef void(*	CrashHandlerCallback) (char , size_t )
	Callback type invoked by CrashHandler when a crash is detected.

using	EventSystem = Events

using	UntrustedArchiveHandler = std::function< bool(Archive &archive, KeystoreEntry &key)>
	Callback invoked when an archive without a trusted key is added.

typedef unsigned long	SearchPathDirectory
	Type alias for a search-path directory constant (see NSSearchPathDirectory values above).

typedef unsigned long	SearchPathDomainMask
	Type alias for a domain-mask value (see NSSearchPathDomainMask values above).

Enumerations
enum class	AudioBackend { WASAPI , SDL , COREAUDIO , NUL }
	Identifies the audio backend implementation in use. More...

enum class	ConsoleVariableType { Integer , Float , String , Color , Color24 }
	Discriminator tag for the active field of the CVar union. More...

enum	StickIndex { LEFT_STICK , RIGHT_STICK }
	Identifies which analog stick an axis mapping applies to. More...

enum	Direction { LEFT , RIGHT , UP , DOWN }
	Identifies the direction component of an axis mapping. More...

enum	KbEventType { LUS_KB_EVENT_KEY_DOWN = 0 , LUS_KB_EVENT_KEY_UP = 1 , LUS_KB_EVENT_ALL_KEYS_UP = 2 , LUS_KB_EVENT_MAX }
	Identifies the type of a keyboard event delivered to the input mapping system. More...

enum	KbScancode { LUS_KB_UNKNOWN = 0 , LUS_KB_ESCAPE = 1 , LUS_KB_1 = 2 , LUS_KB_2 = 3 , LUS_KB_3 = 4 , LUS_KB_4 = 5 , LUS_KB_5 = 6 , LUS_KB_6 = 7 , LUS_KB_7 = 8 , LUS_KB_8 = 9 , LUS_KB_9 = 10 , LUS_KB_0 = 11 , LUS_KB_OEM_MINUS = 12 , LUS_KB_OEM_PLUS = 13 , LUS_KB_BACKSPACE = 14 , LUS_KB_TAB = 15 , LUS_KB_Q = 16 , LUS_KB_W = 17 , LUS_KB_E = 18 , LUS_KB_R = 19 , LUS_KB_T = 20 , LUS_KB_Y = 21 , LUS_KB_U = 22 , LUS_KB_I = 23 , LUS_KB_O = 24 , LUS_KB_P = 25 , LUS_KB_OEM_4 = 26 , LUS_KB_OEM_6 = 27 , LUS_KB_ENTER = 28 , LUS_KB_CONTROL = 29 , LUS_KB_A = 30 , LUS_KB_S = 31 , LUS_KB_D = 32 , LUS_KB_F = 33 , LUS_KB_G = 34 , LUS_KB_H = 35 , LUS_KB_J = 36 , LUS_KB_K = 37 , LUS_KB_L = 38 , LUS_KB_OEM_1 = 39 , LUS_KB_OEM_7 = 40 , LUS_KB_OEM_3 = 41 , LUS_KB_SHIFT = 42 , LUS_KB_OEM_5 = 43 , LUS_KB_Z = 44 , LUS_KB_X = 45 , LUS_KB_C = 46 , LUS_KB_V = 47 , LUS_KB_B = 48 , LUS_KB_N = 49 , LUS_KB_M = 50 , LUS_KB_OEM_COMMA = 51 , LUS_KB_OEM_PERIOD = 52 , LUS_KB_OEM_2 = 53 , LUS_KB_RSHIFT = 54 , LUS_KB_MULTIPLY = 55 , LUS_KB_ALT = 56 , LUS_KB_SPACE = 57 , LUS_KB_CAPSLOCK = 58 , LUS_KB_F1 = 59 , LUS_KB_F2 = 60 , LUS_KB_F3 = 61 , LUS_KB_F4 = 62 , LUS_KB_F5 = 63 , LUS_KB_F6 = 64 , LUS_KB_F7 = 65 , LUS_KB_F8 = 66 , LUS_KB_F9 = 67 , LUS_KB_F10 = 68 , LUS_KB_PAUSE = 69 , LUS_KB_SCROLL = 70 , LUS_KB_NUMPAD7 = 71 , LUS_KB_NUMPAD8 = 72 , LUS_KB_NUMPAD9 = 73 , LUS_KB_SUBTRACT = 74 , LUS_KB_NUMPAD4 = 75 , LUS_KB_NUMPAD5 = 76 , LUS_KB_NUMPAD6 = 77 , LUS_KB_ADD = 78 , LUS_KB_NUMPAD1 = 79 , LUS_KB_NUMPAD2 = 80 , LUS_KB_NUMPAD3 = 81 , LUS_KB_NUMPAD0 = 82 , LUS_KB_NUMPAD_DEL = 83 , LUS_KB_PRINTSCREEN = 84 , LUS_KB_F11 = 87 , LUS_KB_F12 = 88 , LUS_KB_F13 = 124 , LUS_KB_F14 = 125 , LUS_KB_F15 = 126 , LUS_KB_F16 = 127 , LUS_KB_F17 = 128 , LUS_KB_F18 = 129 , LUS_KB_F19 = 130 , LUS_KB_F20 = 131 , LUS_KB_F21 = 132 , LUS_KB_F22 = 133 , LUS_KB_F23 = 134 , LUS_KB_F24 = 135 , LUS_KB_ARROWKEY_UP = 328 , LUS_KB_ARROWKEY_LEFT = 331 , LUS_KB_ARROWKEY_RIGHT = 333 , LUS_KB_ARROWKEY_DOWN = 336 , LUS_KB_MAX }
	Platform-independent keyboard scan codes used by the input mapping system. More...

enum	MouseBtn { LUS_MOUSE_BTN_LEFT , LUS_MOUSE_BTN_MIDDLE , LUS_MOUSE_BTN_RIGHT , LUS_MOUSE_BTN_BACKWARD , LUS_MOUSE_BTN_FORWARD , LUS_MOUSE_BTN_COUNT , LUS_MOUSE_BTN_UNKNOWN }
	Identifies a mouse button delivered to the input mapping system. More...

enum	WheelDirection { LUS_WHEEL_NONE , LUS_WHEEL_LEFT , LUS_WHEEL_RIGHT , LUS_WHEEL_UP , LUS_WHEEL_DOWN , LUS_WHEEL_UNKNOWN }
	Identifies a scroll-wheel direction delivered to the input mapping system. More...

enum	Axis { X = 0 , Y = 1 }
	Identifies a two-dimensional axis component. More...

enum	AxisDirection { NEGATIVE = -1 , POSITIVE = 1 }
	Identifies the sign of an axis value (negative or positive half). More...

enum	PhysicalDeviceType { Keyboard = 0 , Mouse = 1 , SDLGamepad = 2 , Max = 3 }
	Identifies the category of a physical input device. More...

enum class	ClockType : uint64_t { Start , End , PreviousStart , PreviousEnd , ClockMax }
	Identifies a profiling time-point within an Action or Tickable. More...

enum class	ComponentListRole { None , Children , Parents }
	Describes the role of a ComponentList within a parent/child relationship. More...

enum class	ListReturnCode : int32_t { ForcedSuccess = 2 , Success = 1 , Duplicate = 0 , NoItemsProvided = -1 , NotPermitted = -2 , NotFound = -3 , Failed = -4 }
	Return codes for PartList add/remove operations. More...

enum class	TickGroup : uint32_t { TickGroupDefault = 0 }
	Groups TickableComponents into logical tick categories. More...

enum class	TickPriority : uint32_t { TickPriorityDefault = 0 }
	Controls execution order within a TickGroup (lower runs first). More...

enum class	ArgumentType { TEXT , NUMBER }
	Describes the expected type of a command argument. More...

enum class	ResourceType { None = 0x00000000 , Blob = 0x4F424C42 , Json = 0x4A534F4E , Shader = 0x53484144 }
	Numeric type identifiers for built-in resource types. More...

enum class	SafeLevel { DISABLE_SCRIPTS , ONLY_TRUSTED_SCRIPTS , WARN_UNTRUSTED_SCRIPTS , ALLOW_ALL_SCRIPTS }
	Security level controlling which scripts are allowed to load and execute. More...

enum class	KeyOrigin { User , Game , System }
	Describes where a key originated. More...

enum	{ NSApplicationDirectory = 1 , NSDemoApplicationDirectory , NSDeveloperApplicationDirectory , NSAdminApplicationDirectory , NSLibraryDirectory , NSDeveloperDirectory , NSUserDirectory , NSDocumentationDirectory , NSDocumentDirectory , NSCoreServiceDirectory , NSAutosavedInformationDirectory = 11 , NSDesktopDirectory = 12 , NSCachesDirectory = 13 , NSApplicationSupportDirectory = 14 , NSDownloadsDirectory = 15 , NSInputMethodsDirectory = 16 , NSMoviesDirectory = 17 , NSMusicDirectory = 18 , NSPicturesDirectory = 19 , NSPrinterDescriptionDirectory = 20 , NSSharedPublicDirectory = 21 , NSPreferencePanesDirectory = 22 , NSApplicationScriptsDirectory = 23 , NSItemReplacementDirectory = 99 , NSAllApplicationsDirectory = 100 , NSAllLibrariesDirectory = 101 , NSTrashDirectory = 102 }
	macOS / iOS standard-directory constants mirroring NSSearchPathDirectory. More...

enum	{ NSUserDomainMask = 1 , NSLocalDomainMask = 2 , NSNetworkDomainMask = 4 , NSSystemDomainMask = 8 , NSAllDomainsMask = 0x0ffff }
	macOS / iOS domain-mask constants mirroring NSSearchPathDomainMask. More...

enum class	SeekOffsetType { Start , Current , End }
	Identifies the reference point for a seek operation. More...

enum class	OverlayType { TEXT , IMAGE , NOTIFICATION }
	Identifies the type of an overlay item rendered by GameOverlay. More...

Functions
bool	stob (const std::string &s, bool defaultVal=false)
	Converts a string to a boolean value.

int32_t	stoi (const std::string &s, int32_t defaultVal=0)
	Converts a string to a 32-bit signed integer.

float	stof (const std::string &s, float defaultVal=1.0f)
	Converts a string to a float.

int64_t	stoll (const std::string &s, int64_t defaultVal=0)
	Converts a string to a 64-bit signed integer.

std::vector< std::string >	splitText (const std::string &text, char separator, bool keepQuotes)
	Splits `text` at each `separator` character, optionally preserving quoted spans.

std::string	toLowerCase (std::string in)
	Returns a copy of `in` with all ASCII letters converted to lower case.

Variables
static std::string	mouseBtnNames [7]
	Human-readable names for each MouseBtn enumerator.

static std::string	wheelDirectionNames [6]
	Human-readable names for each WheelDirection enumerator.

constexpr uint32_t	Version = SHIP_VERSION_U32

Detailed Description

Core namespace for the libultraship engine framework.

The Ship namespace contains all public types that form the libultraship engine — a component-based framework for running N64 game re-implementations on modern desktop and mobile hardware.

Key subsystems inside Ship include:

Context — the root singleton that owns every other component.
Resource — asset loading, archive management, and caching.
Window / Gui — platform-agnostic windowing, input, and ImGui overlay.
Audio — mixing and playback through platform audio backends.
Controller — unified controller input with configurable mappings.
Console — developer console with console variables and commands.
Events — a publish/subscribe event bus for decoupled communication.
Scripting — optional dynamic library loading for game-specific plugins.

Ship is intentionally platform-neutral; platform-specific code lives behind compile-time feature guards (e.g. ENABLE_DX11, ENABLE_OPENGL) and is abstracted by the subsystem interfaces listed above.

Typedef Documentation

◆ CommandHandler

typedef std::function<int32_t(std::shared_ptr<Console> console, std::vector<std::string> args, std::string* output)> Ship::CommandHandler

Signature of a function that handles a console command.

Parameters

console	Shared pointer to the owning Console (for recursive dispatch).
args	Tokenised command arguments (index 0 is the command name).
output	If non-null, the handler should write its response here.

Returns: 0 on success, non-zero on error.

◆ ComponentList

using Ship::ComponentList = typedef BasicComponentList<std::shared_ptr<Component> >

Owning child-component list storage type.

◆ ConsoleVariableType

typedef enum Ship::ConsoleVariableType Ship::ConsoleVariableType

Discriminator tag for the active field of the CVar union.

◆ CrashHandlerCallback

typedef void(* Ship::CrashHandlerCallback) (char *, size_t *)

Callback type invoked by CrashHandler when a crash is detected.

The callback receives a mutable character buffer (char*) and its current write position (size_t*) so that it can append additional context to the crash report before it is flushed.

◆ CVar

typedef struct Ship::CVar Ship::CVar

A single console variable (CVar) holding a typed value.

CVars are the primary runtime-tunable settings system. Each CVar stores exactly one value whose type is determined by the Type field. The union members Integer, Float, String, Color, and Color24 are mutually exclusive.

Note: The String member is heap-allocated and is freed by the destructor.

◆ EventActionCallback

using Ship::EventActionCallback = typedef std::variant<std::monostate, EventActionCppCallback, uintptr_t>

Stored callback target for EventAction.

std::monostate: no callback override (fallback to TickableComponent dispatch)
EventActionCppCallback: C++ callback override
uintptr_t: C-style function pointer override

◆ EventActionCppCallback

using Ship::EventActionCppCallback = typedef std::function<bool(EventID, uintptr_t)>

C++ callback signature for EventAction dispatch.

Parameters

eventId	Event being dispatched.
callbackPointerData	Opaque pointer-sized data supplied by EventAction.

Returns: True when callback handled successfully.

◆ EventActionRawCallback

using Ship::EventActionRawCallback = typedef bool (*)(EventID, uintptr_t)

C-style callback signature for EventAction dispatch.

Stored in EventAction as uintptr_t and cast at dispatch time.

◆ EventSystem

using Ship::EventSystem = typedef Events

◆ KbEventType

typedef enum Ship::KbEventType Ship::KbEventType

Identifies the type of a keyboard event delivered to the input mapping system.

◆ KbScancode

typedef enum Ship::KbScancode Ship::KbScancode

Platform-independent keyboard scan codes used by the input mapping system.

Values are based on the PS/2 set-1 scan code layout so they remain stable across operating systems. Use these constants when registering keyboard bindings via the ControllerButtonMapping and ControllerAxisDirectionMapping APIs.

◆ MouseBtn

typedef enum Ship::MouseBtn Ship::MouseBtn

Identifies a mouse button delivered to the input mapping system.

◆ ParentComponentList

using Ship::ParentComponentList = typedef BasicComponentList<std::weak_ptr<Component> >

Non-owning parent-component list storage type.

◆ SearchPathDirectory

typedef unsigned long Ship::SearchPathDirectory

Type alias for a search-path directory constant (see NSSearchPathDirectory values above).

◆ SearchPathDomainMask

typedef unsigned long Ship::SearchPathDomainMask

Type alias for a domain-mask value (see NSSearchPathDomainMask values above).

◆ UntrustedArchiveHandler

using Ship::UntrustedArchiveHandler = typedef std::function<bool(Archive& archive, KeystoreEntry& key)>

Callback invoked when an archive without a trusted key is added.

The handler receives a reference to the untrusted Archive and the key entry from the Keystore. Return true to accept the archive anyway, or false to reject it.

◆ WheelDirection

typedef enum Ship::WheelDirection Ship::WheelDirection

Identifies a scroll-wheel direction delivered to the input mapping system.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

macOS / iOS standard-directory constants mirroring NSSearchPathDirectory.

These values match the macOS SDK's NSSearchPathDirectory enumeration so that the Ship code can locate standard directories (Documents, Caches, Application Support, etc.) without introducing an Objective-C dependency in C++ translation units.

Enumerator
NSApplicationDirectory	Applications directory (/Applications).
NSDemoApplicationDirectory	Demonstration applications directory.
NSDeveloperApplicationDirectory	Developer applications directory.
NSAdminApplicationDirectory	Administration applications directory.
NSLibraryDirectory	Library directory.
NSDeveloperDirectory	Developer tools directory.
NSUserDirectory	User home directories (~/...).
NSDocumentationDirectory	Documentation directory.
NSDocumentDirectory	Documents directory (~/Documents).
NSCoreServiceDirectory	Core services directory.
NSAutosavedInformationDirectory	Autosaved information directory.
NSDesktopDirectory	Desktop directory (~/Desktop).
NSCachesDirectory	Caches directory (~/Library/Caches).
NSApplicationSupportDirectory	Application support directory (~/Library/Application Support).
NSDownloadsDirectory	Downloads directory (~/Downloads).
NSInputMethodsDirectory	Input methods directory.
NSMoviesDirectory	Movies directory (~/Movies).
NSMusicDirectory	Music directory (~/Music).
NSPicturesDirectory	Pictures directory (~/Pictures).
NSPrinterDescriptionDirectory	Printer description directory.
NSSharedPublicDirectory	Public directory (~/Public).
NSPreferencePanesDirectory	Preference panes directory.
NSApplicationScriptsDirectory	Application scripts directory.
NSItemReplacementDirectory	Temporary directory suitable for atomic file replacement.
NSAllApplicationsDirectory	All applications directories.
NSAllLibrariesDirectory	All library directories.
NSTrashDirectory	Trash directory.

◆ anonymous enum

anonymous enum

macOS / iOS domain-mask constants mirroring NSSearchPathDomainMask.

Domain masks are used together with SearchPathDirectory values to restrict which domain(s) FolderManager searches when locating a standard directory.

Enumerator
NSUserDomainMask	User's home directory (~).
NSLocalDomainMask	Local machine directory (/Library).
NSNetworkDomainMask	Network directory (/Network).
NSSystemDomainMask	System directory (/System) — provided by Apple, unmodifiable.
NSAllDomainsMask	All domains.

◆ ArgumentType

enum class Ship::ArgumentType

strong

Describes the expected type of a command argument.

Enumerator
TEXT
NUMBER

◆ AudioBackend

enum class Ship::AudioBackend

strong

Identifies the audio backend implementation in use.

Enumerator
WASAPI
SDL
COREAUDIO
NUL

◆ Axis

enum Ship::Axis

Identifies a two-dimensional axis component.

Enumerator
X
Y

◆ AxisDirection

enum Ship::AxisDirection

Identifies the sign of an axis value (negative or positive half).

Enumerator
NEGATIVE
POSITIVE

◆ ClockType

enum class Ship::ClockType : uint64_t

strong

Identifies a profiling time-point within an Action or Tickable.

Used to query start/end timestamps of the current and previous execution cycles.

Enumerator
Start
End
PreviousStart
PreviousEnd
ClockMax

◆ ComponentListRole

enum class Ship::ComponentListRole

strong

Describes the role of a ComponentList within a parent/child relationship.

When a ComponentList has a role, its Added()/Removed() hooks automatically maintain the bidirectional relationship on the linked Component.

Enumerator
None	No automatic relationship management.
Children	This list holds children; adding updates the child's parent list.
Parents	This list holds parents; adding updates the parent's child list.

◆ ConsoleVariableType

enum class Ship::ConsoleVariableType

strong

Discriminator tag for the active field of the CVar union.

Enumerator
Integer
Float
String
Color
Color24

◆ Direction

enum Ship::Direction

Identifies the direction component of an axis mapping.

Enumerator
LEFT
RIGHT
UP
DOWN

◆ KbEventType

enum Ship::KbEventType

Identifies the type of a keyboard event delivered to the input mapping system.

Enumerator
LUS_KB_EVENT_KEY_DOWN	A key was pressed.
LUS_KB_EVENT_KEY_UP	A key was released.
LUS_KB_EVENT_ALL_KEYS_UP	All keys were released simultaneously (e.g. window lost focus).
LUS_KB_EVENT_MAX	Sentinel — do not use as an event type.

◆ KbScancode

enum Ship::KbScancode

Platform-independent keyboard scan codes used by the input mapping system.

Values are based on the PS/2 set-1 scan code layout so they remain stable across operating systems. Use these constants when registering keyboard bindings via the ControllerButtonMapping and ControllerAxisDirectionMapping APIs.

Enumerator
LUS_KB_UNKNOWN
LUS_KB_ESCAPE
LUS_KB_1
LUS_KB_2
LUS_KB_3
LUS_KB_4
LUS_KB_5
LUS_KB_6
LUS_KB_7
LUS_KB_8
LUS_KB_9
LUS_KB_0
LUS_KB_OEM_MINUS
LUS_KB_OEM_PLUS
LUS_KB_BACKSPACE
LUS_KB_TAB
LUS_KB_Q
LUS_KB_W
LUS_KB_E
LUS_KB_R
LUS_KB_T
LUS_KB_Y
LUS_KB_U
LUS_KB_I
LUS_KB_O
LUS_KB_P
LUS_KB_OEM_4	Open bracket ([) / brace ({) on a US keyboard.
LUS_KB_OEM_6	Close bracket (]) / brace (}) on a US keyboard.
LUS_KB_ENTER
LUS_KB_CONTROL
LUS_KB_A
LUS_KB_S
LUS_KB_D
LUS_KB_F
LUS_KB_G
LUS_KB_H
LUS_KB_J
LUS_KB_K
LUS_KB_L
LUS_KB_OEM_1	Semicolon (;) / colon (:) on a US keyboard.
LUS_KB_OEM_7	Single quote (') / double quote (") on a US keyboard.
LUS_KB_OEM_3	Grave (`) / tilde (~) on a US keyboard.
LUS_KB_SHIFT
LUS_KB_OEM_5	Backslash () / pipe (\|) on a US keyboard.
LUS_KB_Z
LUS_KB_X
LUS_KB_C
LUS_KB_V
LUS_KB_B
LUS_KB_N
LUS_KB_M
LUS_KB_OEM_COMMA
LUS_KB_OEM_PERIOD
LUS_KB_OEM_2	Slash (/) / question mark (?) on a US keyboard.
LUS_KB_RSHIFT
LUS_KB_MULTIPLY	Asterisk (*) on the numeric keypad.
LUS_KB_ALT
LUS_KB_SPACE
LUS_KB_CAPSLOCK
LUS_KB_F1
LUS_KB_F2
LUS_KB_F3
LUS_KB_F4
LUS_KB_F5
LUS_KB_F6
LUS_KB_F7
LUS_KB_F8
LUS_KB_F9
LUS_KB_F10	Generally inadvisable to bind — this is a Windows system key.
LUS_KB_PAUSE
LUS_KB_SCROLL
LUS_KB_NUMPAD7
LUS_KB_NUMPAD8
LUS_KB_NUMPAD9
LUS_KB_SUBTRACT	Minus (-) on the numeric keypad.
LUS_KB_NUMPAD4
LUS_KB_NUMPAD5
LUS_KB_NUMPAD6
LUS_KB_ADD	Plus (+) on the numeric keypad.
LUS_KB_NUMPAD1
LUS_KB_NUMPAD2
LUS_KB_NUMPAD3
LUS_KB_NUMPAD0
LUS_KB_NUMPAD_DEL
LUS_KB_PRINTSCREEN
LUS_KB_F11
LUS_KB_F12
LUS_KB_F13
LUS_KB_F14
LUS_KB_F15
LUS_KB_F16
LUS_KB_F17
LUS_KB_F18
LUS_KB_F19
LUS_KB_F20
LUS_KB_F21
LUS_KB_F22
LUS_KB_F23
LUS_KB_F24
LUS_KB_ARROWKEY_UP
LUS_KB_ARROWKEY_LEFT
LUS_KB_ARROWKEY_RIGHT
LUS_KB_ARROWKEY_DOWN
LUS_KB_MAX	Sentinel — do not use as a scan code.

◆ KeyOrigin

enum class Ship::KeyOrigin

strong

Describes where a key originated.

Used to categorize keys so that system-managed and user-supplied keys can be distinguished from keys bundled with game archives.

Enumerator
User
Game
System

◆ ListReturnCode

enum class Ship::ListReturnCode : int32_t

strong

Return codes for PartList add/remove operations.

Non-negative values (>= 0) indicate the Part is guaranteed to be in the list after the operation. Negative values indicate an error. A value > 0 means a Part was actually added/removed; == 0 means the list is unchanged (duplicate).

Enumerator
ForcedSuccess	Operation succeeded via force override.
Success	Operation succeeded normally.
Duplicate	Part already present; list unchanged.
NoItemsProvided	The input collection was empty.
NotPermitted	Operation blocked by a permission check.
NotFound	The specified Part was not found.
Failed	General failure (e.g. null pointer).

◆ MouseBtn

enum Ship::MouseBtn

Identifies a mouse button delivered to the input mapping system.

Enumerator
LUS_MOUSE_BTN_LEFT	Primary (left) mouse button.
LUS_MOUSE_BTN_MIDDLE	Middle (scroll wheel) mouse button.
LUS_MOUSE_BTN_RIGHT	Secondary (right) mouse button.
LUS_MOUSE_BTN_BACKWARD	Backward / side button (button 4).
LUS_MOUSE_BTN_FORWARD	Forward / side button (button 5).
LUS_MOUSE_BTN_COUNT	Number of named mouse buttons.
LUS_MOUSE_BTN_UNKNOWN	An unrecognised or unmapped mouse button.

◆ OverlayType

enum class Ship::OverlayType

strong

Identifies the type of an overlay item rendered by GameOverlay.

Enumerator
TEXT	A fixed-position text label.
IMAGE	An image drawn at a screen position.
NOTIFICATION	A transient notification that fades out after a duration.

◆ PhysicalDeviceType

enum Ship::PhysicalDeviceType

Identifies the category of a physical input device.

Used throughout the controller mapping system to distinguish between different classes of hardware when creating or looking up input mappings.

Enumerator
Keyboard	Standard keyboard.
Mouse	Mouse (buttons and motion).
SDLGamepad	SDL-managed game controller.
Max	Sentinel / count of device types.

◆ ResourceType

enum class Ship::ResourceType

strong

Numeric type identifiers for built-in resource types.

Each enumerator's underlying value is the four-character ASCII code of the type as a big-endian 32-bit integer, making the value human-readable in a hex dump (e.g. Blob == 'OBLB').

Custom resource types should use values outside the Ship-reserved range and register them with ResourceLoader::RegisterResourceFactory().

Enumerator
None
Blob	Generic binary blob ("OBLB")
Json	JSON document ("JSON")
Shader	Shader program ("SHAD")

◆ SafeLevel

enum class Ship::SafeLevel

strong

Security level controlling which scripts are allowed to load and execute.

Enumerator
DISABLE_SCRIPTS	No scripts are loaded or executed.
ONLY_TRUSTED_SCRIPTS	Only scripts from signed/trusted archives are loaded.
WARN_UNTRUSTED_SCRIPTS	Untrusted scripts are loaded with a warning.
ALLOW_ALL_SCRIPTS	All scripts are loaded without restriction.

◆ SeekOffsetType

enum class Ship::SeekOffsetType

strong

Identifies the reference point for a seek operation.

Enumerator
Start	Seek relative to the beginning of the stream.
Current	Seek relative to the current position.
End	Seek relative to the end of the stream.

◆ StickIndex

enum Ship::StickIndex

Identifies which analog stick an axis mapping applies to.

Enumerator
LEFT_STICK
RIGHT_STICK

◆ TickGroup

enum class Ship::TickGroup : uint32_t

strong

Groups TickableComponents into logical tick categories.

Enumerator
TickGroupDefault

◆ TickPriority

enum class Ship::TickPriority : uint32_t

strong

Controls execution order within a TickGroup (lower runs first).

Enumerator
TickPriorityDefault

◆ WheelDirection

enum Ship::WheelDirection

Identifies a scroll-wheel direction delivered to the input mapping system.

Enumerator
LUS_WHEEL_NONE	No scroll (initial or reset state).
LUS_WHEEL_LEFT	Horizontal scroll to the left.
LUS_WHEEL_RIGHT	Horizontal scroll to the right.
LUS_WHEEL_UP	Vertical scroll upward.
LUS_WHEEL_DOWN	Vertical scroll downward.
LUS_WHEEL_UNKNOWN	An unrecognised scroll direction.

Function Documentation

◆ splitText()

std::vector< std::string > Ship::splitText	(	const std::string &	text,
		char	separator,
		bool	keepQuotes
	)

Splits text at each separator character, optionally preserving quoted spans.

Parameters

text	Input string to split.
separator	Delimiter character.
keepQuotes	If true, quoted spans (delimited by `"`) are not split even if they contain `separator`.

Returns: Vector of token strings (separators are not included).

◆ stob()

bool Ship::stob	(	const std::string &	s,
		bool	defaultVal = `false`
	)

Converts a string to a boolean value.

First attempts a numeric integer parse: "0" → false, any other integer → true. If that fails, retries with std::boolalpha, which accepts "false" → false and "true" → true (locale-dependent, but typically case-sensitive for the "C" locale). If both attempts fail, returns defaultVal and logs a debug message.

Parameters

s	String to convert.
defaultVal	Value returned when `s` cannot be parsed as a boolean.

Returns: Parsed boolean, or defaultVal on failure.

◆ stof()

float Ship::stof	(	const std::string &	s,
		float	defaultVal = `1.0f`
	)

Converts a string to a float.

Parameters

s	String to convert.
defaultVal	Value returned when conversion fails.

Returns: Parsed float, or defaultVal on failure.

◆ stoi()

int32_t Ship::stoi	(	const std::string &	s,
		int32_t	defaultVal = `0`
	)

Converts a string to a 32-bit signed integer.

Parameters

s	String to convert.
defaultVal	Value returned when conversion fails.

Returns: Parsed integer, or defaultVal on failure.

◆ stoll()

int64_t Ship::stoll	(	const std::string &	s,
		int64_t	defaultVal = `0`
	)

Converts a string to a 64-bit signed integer.

Parameters

s	String to convert.
defaultVal	Value returned when conversion fails.

Returns: Parsed 64-bit integer, or defaultVal on failure.

◆ toLowerCase()

std::string Ship::toLowerCase ( std::string in )

Returns a copy of in with all ASCII letters converted to lower case.

Parameters

in	Input string.

Returns: Lower-cased copy.

Variable Documentation

◆ mouseBtnNames

std::string Ship::mouseBtnNames[7]

static

Initial value:

= { "MouseLeft", "MouseMiddle", "MouseRight", "MouseBackward",

"MouseForward", "MOUSE_BTN_COUNT", "MOUSE_BTN_UNKNOWN" }

Human-readable names for each MouseBtn enumerator.

◆ Version

constexpr uint32_t Ship::Version = SHIP_VERSION_U32

inlineconstexpr

◆ wheelDirectionNames

std::string Ship::wheelDirectionNames[6]

static

Initial value:

= { "LUS_WHEEL_NONE", "WheelLeft", "WheelRight",

"WheelUp", "WheelDown", "LUS_WHEEL_UNKNOWN" }

Human-readable names for each WheelDirection enumerator.

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ CommandHandler

◆ ComponentList

◆ ConsoleVariableType

◆ CrashHandlerCallback

◆ CVar

◆ EventActionCallback

◆ EventActionCppCallback

◆ EventActionRawCallback

◆ EventSystem

◆ KbEventType

◆ KbScancode

◆ MouseBtn

◆ ParentComponentList

◆ SearchPathDirectory

◆ SearchPathDomainMask

◆ UntrustedArchiveHandler

◆ WheelDirection

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ ArgumentType

◆ AudioBackend

◆ Axis

◆ AxisDirection

◆ ClockType

◆ ComponentListRole

◆ ConsoleVariableType

◆ Direction

◆ KbEventType

◆ KbScancode

◆ KeyOrigin

◆ ListReturnCode

◆ MouseBtn

◆ OverlayType

◆ PhysicalDeviceType

◆ ResourceType

◆ SafeLevel

◆ SeekOffsetType

◆ StickIndex

◆ TickGroup

◆ TickPriority

◆ WheelDirection

Function Documentation

◆ splitText()

◆ stob()

◆ stof()

◆ stoi()

◆ stoll()

◆ toLowerCase()

Variable Documentation

◆ mouseBtnNames

◆ Version

◆ wheelDirectionNames