Engine¶

Description¶

Control engine properties and define defaults used across the whole project. Engine is entirely static — never instantiated. It manages the scene stack, canvas size and scaling, the update loop, platform queries, and all frame/input callback events.

#include "Doriax.h"
using namespace doriax;

Scene scene;

DORIAX_INIT void init() {
    Engine::setCanvasSize(1000, 480);
    Engine::setScalingMode(Scaling::FITWIDTH);
    Engine::setScene(&scene);
}

scene = Scene()
Engine.setCanvasSize(1000, 480)
Engine.scalingMode = Scaling.FITWIDTH
Engine.setScene(scene)

Properties¶

Methods¶

Callback events¶

Enumerations¶

Scaling¶

• FITWIDTH — Keeps canvas width fixed; height floats to match aspect ratio.
• FITHEIGHT — Keeps canvas height fixed; width floats.
• LETTERBOX — Keeps both dimensions; empty bars appear on screen edges.
• CROP — Keeps both dimensions; parts of the canvas may be cropped off screen.
• STRETCH — Stretches to fill the screen; objects may deform.
• NATIVE — Uses the native window resolution as-is.

TextureStrategy¶

• FIT — Adjusts non-power-of-two textures using a fit algorithm.
• RESIZE — Resizes textures to the next power of two.
• NONE — No automatic texture resizing.

Platform¶

• MacOS — Running on macOS.
• iOS — Running on iOS.
• Web — Running in WebGL/HTML5.
• Android — Running on Android.
• Linux — Running on Linux.
• Windows — Running on Windows.

GraphicBackend¶

• GLCORE — OpenGL Core (desktop).
• GLES3 — OpenGL ES 3 (mobile/web).
• D3D11 — Direct3D 11 (Windows).
• METAL — Metal (Apple platforms).
• WGPU — WebGPU.

CursorType¶

ARROW, IBEAM, CROSSHAIR, POINTING_HAND, RESIZE_EW, RESIZE_NS, RESIZE_NWSE, RESIZE_NESW, RESIZE_ALL, NOT_ALLOWED

Property details¶

scalingMode¶

• Setter: static void setScalingMode(Scaling scalingMode)
• Getter: static Scaling getScalingMode()

Controls how the logical canvas is mapped to the physical window. See Scaling for each mode.

textureStrategy¶

• Setter: static void setTextureStrategy(TextureStrategy textureStrategy)
• Getter: static TextureStrategy getTextureStrategy()

Controls automatic resizing of non-power-of-two textures on hardware that requires it.

callMouseInTouchEvent¶

• Setter: static void setCallMouseInTouchEvent(bool callMouseInTouchEvent)
• Getter: static bool isCallMouseInTouchEvent()

When true, receiving a touch event also fires the equivalent mouse event. Useful for cross-platform testing.

callTouchInMouseEvent¶

• Setter: static void setCallTouchInMouseEvent(bool callTouchInMouseEvent)
• Getter: static bool isCallTouchInMouseEvent()

When true, receiving a mouse event also fires the equivalent touch event.

useDegrees¶

• Setter: static void setUseDegrees(bool useDegrees)
• Getter: static bool isUseDegrees()

When true (default), angle parameters in the API expect degrees. Set to false to use radians throughout.

allowEventsOutCanvas¶

• Setter: static void setAllowEventsOutCanvas(bool allowEventsOutCanvas)
• Getter: static bool isAllowEventsOutCanvas()

When true, mouse move and scroll events are delivered even when the cursor is outside the canvas bounds.

ignoreEventsHandledByUI¶

• Setter: static void setIgnoreEventsHandledByUI(bool ignoreEventsHandledByUI)
• Getter: static bool isIgnoreEventsHandledByUI()

When true, gameplay input callbacks are skipped for events already consumed by a UI widget.

updateTime¶

• Setter: static void setUpdateTime(float updateTime)
• Getter: static float getUpdateTime()

Fixed-update interval in seconds. Used by onFixedUpdate and the physics simulation step. Also accepted in milliseconds via setUpdateTimeMS.

interpolationAlpha¶

• Getter: static double getInterpolationAlpha()

Value in [0, 1) representing how far the current rendered frame is between the previous and next fixed-update steps. Use to visually interpolate physics-driven entities and avoid temporal aliasing.

canvasWidth / canvasHeight¶

• Getter: static int getCanvasWidth() / static int getCanvasHeight()

Logical canvas dimensions after scaling is applied. These may differ from preferredCanvasWidth when a non-NATIVE scaling mode is active.

preferredCanvasWidth / preferredCanvasHeight¶

• Getter: static int getPreferredCanvasWidth() / static int getPreferredCanvasHeight()

The dimensions originally passed to setCanvasSize, unaffected by scaling.

viewRect¶

• Getter: static Rect getViewRect()

Viewport rectangle computed from canvas size, screen size, and scaling mode.

deltatime¶

• Getter: static float getDeltatime()

Time elapsed in seconds since the last draw frame. Multiply movement speeds by deltatime inside onUpdate to make motion frame-rate independent.

framerate¶

• Getter: static float getFramerate()

Current frames-per-second estimate.

systemTime¶

• Getter: static double getSystemTime()

Monotonic wall-clock time in seconds, independent of scene pausing and update loop throttling.

platform¶

• Getter: static Platform getPlatform()

Returns the Platform the engine is currently running on.

graphicBackend¶

• Getter: static GraphicBackend getGraphicBackend()

Returns the active GraphicBackend.

openGL¶

• Getter: static bool isOpenGL()

Returns true when any OpenGL backend (GLCORE, GLES3) is active.

asyncLoading¶

• Setter: static void setAsyncLoading(bool enable)
• Getter: static bool isAsyncLoading()

Enable background resource loading. When active, GPU resource creation must be committed on the main thread via commitThreadQueue.

mouseCursor¶

• Setter: static void setMouseCursor(CursorType type)
• Getter: static CursorType getMouseCursor()

Changes the OS mouse cursor shape. See CursorType.

framebuffer¶

• Setter: static void setFramebuffer(Framebuffer* framebuffer)
• Getter: static Framebuffer* getFramebuffer()

Off-screen render target for the full frame output. When set, the engine renders to this framebuffer instead of the window surface.

Method details¶

setScene¶

• static void setScene(Scene* scene)

Sets the main scene. Pass nullptr (C++) or nil (Lua) to clear the main scene.

getScene¶

• static Scene* getScene()

Returns the current main scene, or nullptr/nil if none is set.

addSceneLayer¶

• static void addSceneLayer(Scene* scene)

Renders an additional scene as a layer on top of the main scene. Commonly used for HUDs, overlays, or pause menus.

executeSceneOnce¶

• static void executeSceneOnce(Scene* scene)

Adds a scene that runs for exactly one update/draw cycle, then is automatically removed. Useful for single-frame splash transitions.

removeScene¶

• static void removeScene(Scene* scene)

Removes a specific scene from the active scene stack.

removeAllSceneLayers¶

• static void removeAllSceneLayers(bool removeOneTimeScenes)

Removes all layered scenes. When removeOneTimeScenes is true, one-time scenes added via executeSceneOnce are also removed.

removeAllScenes¶

• static void removeAllScenes()

Removes all scenes, including the main scene and all layers.

isSceneRunning¶

• static bool isSceneRunning(Scene* scene)

Returns true if the given scene is currently in the active scene stack.

getMainScene¶

• static Scene* getMainScene()

Returns the scene set with setScene.

getLastScene¶

• static Scene* getLastScene()

Returns the top-most scene in the stack (the most recently added layer, or the main scene if no layers exist).

pauseGameEvents¶

• static void pauseGameEvents(bool pause)

Pauses delivery of gameplay events (onUpdate, onFixedUpdate, input callbacks) without stopping the render loop. The editor uses this when the project is not in play mode.

setCanvasSize¶

• static void setCanvasSize(int canvasWidth, int canvasHeight)

Sets the preferred logical canvas dimensions. The actual canvasWidth/canvasHeight reported at runtime may differ depending on the active scalingMode.

getViewRect¶

• static Rect getViewRect()

Returns the viewport rectangle calculated from canvas size, window size, and scaling mode.

setUpdateTimeMS¶

• static void setUpdateTimeMS(unsigned int updateTimeMS)

Same as updateTime but accepts the interval in milliseconds.

isUIEventReceived¶

• static bool isUIEventReceived()

Returns true if any UI widget consumed a pointer event during the current frame. Use with ignoreEventsHandledByUI to prevent gameplay from reacting to UI clicks.

isViewLoaded¶

• static bool isViewLoaded()

Returns true after the graphics surface is ready (after onViewLoaded fires).

clearAllSubscriptions¶

• static void clearAllSubscriptions(bool includeLifecycle)

Removes all registered callbacks from all engine events. When includeLifecycle is false, lifecycle events such as onViewLoaded are preserved.

setMaxResourceLoadingThreads¶

• static void setMaxResourceLoadingThreads(size_t maxThreads)

Sets the maximum number of worker threads used for background asset loading.

getQueuedResourceCount¶

• static size_t getQueuedResourceCount()

Returns the number of resources still waiting to be loaded on background threads.

startAsyncThread / commitThreadQueue / endAsyncThread / isAsyncThread¶

Used to safely create GPU resources from background threads:

1. Call startAsyncThread() at the beginning of the worker function.
2. Create textures, meshes, etc.
3. Call commitThreadQueue() periodically (or at the end) to flush pending GPU uploads on the main thread.
4. Call endAsyncThread() when the worker is finished.

AsyncThreadScope (C++ RAII) wraps start/end automatically.

Callback event details¶

onViewLoaded¶

• static FunctionSubscribe<void()> onViewLoaded

Called once when the graphics backend surface is ready for rendering.

onCanvasChanged¶

• static FunctionSubscribe<void()> onCanvasChanged
• Callback: void()

Called when the canvas or window size changes. Re-query canvasWidth/canvasHeight or reposition UI elements here.

onViewDestroyed¶

• static FunctionSubscribe<void()> onViewDestroyed
• Callback: void()

Called when the graphics surface is being destroyed (e.g. app going to background on mobile).

onDraw¶

• static FunctionSubscribe<void()> onDraw
• Callback: void()

Called every frame after the scene is drawn. Use for custom rendering passes.

onUpdate¶

• static FunctionSubscribe<void()> onUpdate
• Callback: void()

Called every frame for variable-step gameplay logic. Multiply movement by deltatime to ensure frame-rate independence.

onFixedUpdate¶

• static FunctionSubscribe<void()> onFixedUpdate
• Callback: void()

Called at a fixed interval defined by updateTime. Use for physics, deterministic simulation, and anything that must not depend on frame rate.

onPostUpdate¶

• static FunctionSubscribe<void()> onPostUpdate
• Callback: void()

Called after the regular update and fixed-update passes each frame. Useful for late-stage logic such as camera follow that must run after all objects have moved.

onPause¶

• static FunctionSubscribe<void()> onPause
• Callback: void()

Called when the system suspends the application (e.g. phone call received, app moved to background).

onResume¶

• static FunctionSubscribe<void()> onResume
• Callback: void()

Called when the application returns to the foreground after a pause.

onShutdown¶

• static FunctionSubscribe<void()> onShutdown
• Callback: void()

Called when the application is closing. Use to flush saves or clean up persistent state.

onTouchStart¶

• static FunctionSubscribe<void(int,float,float)> onTouchStart
• Callback: void(int pointer, float x, float y)
  • pointer — Touch identifier for multitouch tracking.
  • x — Horizontal position in canvas coordinates.
  • y — Vertical position in canvas coordinates.

Called when a new touch contact begins.

onTouchEnd¶

• static FunctionSubscribe<void(int,float,float)> onTouchEnd
• Callback: void(int pointer, float x, float y)
  • pointer — Touch identifier.
  • x — Final horizontal position in canvas coordinates.
  • y — Final vertical position in canvas coordinates.

Called when a touch contact is lifted.

onTouchMove¶

• static FunctionSubscribe<void(int,float,float)> onTouchMove
• Callback: void(int pointer, float x, float y)
  • pointer — Touch identifier.
  • x — Updated horizontal position.
  • y — Updated vertical position.

Called whenever a touch contact moves.

onTouchCancel¶

• static FunctionSubscribe<void()> onTouchCancel
• Callback: void()

Called when the system cancels the current touch sequence (e.g. an incoming call interrupts input).

onMouseDown¶

• static FunctionSubscribe<void(int,float,float,int)> onMouseDown
• Callback: void(int button, float x, float y, int mods)
  • button — Mouse button index; see Input constants.
  • x — Horizontal position in canvas coordinates.
  • y — Vertical position in canvas coordinates.
  • mods — Modifier key bitmask; see Input.

Called when a mouse button is pressed.

onMouseUp¶

• static FunctionSubscribe<void(int,float,float,int)> onMouseUp
• Callback: void(int button, float x, float y, int mods)
  • button — Mouse button index.
  • x — Horizontal position.
  • y — Vertical position.
  • mods — Modifier key bitmask.

Called when a mouse button is released.

onMouseMove¶

• static FunctionSubscribe<void(float,float,int)> onMouseMove
• Callback: void(float x, float y, int mods)
  • x — Horizontal position in canvas coordinates.
  • y — Vertical position in canvas coordinates.
  • mods — Modifier key bitmask.

Called when the mouse cursor moves. Also called outside the canvas when allowEventsOutCanvas is true.

onMouseScroll¶

• static FunctionSubscribe<void(float,float,int)> onMouseScroll
• Callback: void(float xoffset, float yoffset, int mods)
  • xoffset — Horizontal scroll amount.
  • yoffset — Vertical scroll amount (positive = scroll up).
  • mods — Modifier key bitmask.

Called when the mouse scroll wheel changes.

onMouseEnter¶

• static FunctionSubscribe<void()> onMouseEnter
• Callback: void()

Called when the mouse cursor enters the canvas boundary.

onMouseLeave¶

• static FunctionSubscribe<void()> onMouseLeave
• Callback: void()

Called when the mouse cursor leaves the canvas boundary.

onKeyDown¶

• static FunctionSubscribe<void(int,bool,int)> onKeyDown
• Callback: void(int key, bool repeat, int mods)
  • key — Key code; see Input constants (S_KEY_*).
  • repeat — true if the key is being held and this is a repeat event.
  • mods — Modifier key bitmask.

Called when any keyboard key is pressed.

onKeyUp¶

• static FunctionSubscribe<void(int,bool,int)> onKeyUp
• Callback: void(int key, bool repeat, int mods)
  • key — Key code.
  • repeat — Always false on key-up.
  • mods — Modifier key bitmask.

Called when any keyboard key is released.

onCharInput¶

• static FunctionSubscribe<void(wchar_t)> onCharInput
• Callback: void(wchar_t codepoint)
  • codepoint — Unicode code point of the typed character, including composed/accented characters.

Called for text input. Prefer this over onKeyDown when implementing text fields.