PolyphaseEngineAPI.h

Go to the documentation of this file.

#pragma once
 
#include <stdint.h>
#include <stddef.h>
 
struct lua_State;
struct EditorUIHooks;
struct ImGuiPluginContext;
 
// Forward declarations for engine types
class Node;
class Node3D;
class World;
class Asset;
class SoundWave;
 
struct PolyphaseEngineAPI
{
    // ===== Logging =====
 
    void (*LogDebug)(const char* fmt, ...);
 
    void (*LogWarning)(const char* fmt, ...);
 
    void (*LogError)(const char* fmt, ...);
 
    // ===== Lua Access =====
 
    lua_State* (*GetLua)();
 
    // ===== Lua Wrappers =====
    // These wrap Lua C API functions so plugins don't need to link against Lua.
    // Names use "Lua_" prefix to avoid conflicts with Lua macros.
    // Example: Use sEngineAPI->Lua_pushnumber() instead of lua_pushnumber()
 
    // Stack manipulation
    void (*Lua_settop)(lua_State* L, int idx);
    void (*Lua_pushvalue)(lua_State* L, int idx);
    void (*Lua_pop)(lua_State* L, int n);
    int (*Lua_gettop)(lua_State* L);
 
    // Type checking
    int (*Lua_type)(lua_State* L, int idx);
    int (*Lua_isfunction)(lua_State* L, int idx);
    int (*Lua_istable)(lua_State* L, int idx);
    int (*Lua_isuserdata)(lua_State* L, int idx);
    int (*Lua_isnil)(lua_State* L, int idx);
 
    // Get values
    int (*Lua_toboolean)(lua_State* L, int idx);
    double (*Lua_tonumber)(lua_State* L, int idx);
    const char* (*Lua_tostring)(lua_State* L, int idx);
    void* (*Lua_touserdata)(lua_State* L, int idx);
 
    // Push values
    void (*Lua_pushnil)(lua_State* L);
    void (*Lua_pushboolean)(lua_State* L, int b);
    void (*Lua_pushnumber)(lua_State* L, double n);
    void (*Lua_pushstring)(lua_State* L, const char* s);
    void (*Lua_pushinteger)(lua_State* L, long long n);
 
    // Userdata
    void* (*Lua_newuserdata)(lua_State* L, size_t sz);
 
    // Tables and fields
    void (*Lua_createtable)(lua_State* L, int narr, int nrec);
    void (*Lua_setfield)(lua_State* L, int idx, const char* k);
    void (*Lua_getfield)(lua_State* L, int idx, const char* k);
    void (*Lua_setglobal)(lua_State* L, const char* name);
    void (*Lua_getglobal)(lua_State* L, const char* name);
    void (*Lua_rawset)(lua_State* L, int idx);
    void (*Lua_rawget)(lua_State* L, int idx);
    void (*Lua_settable)(lua_State* L, int idx);
    void (*Lua_gettable)(lua_State* L, int idx);
 
    // Metatables
    int (*Lua_setmetatable)(lua_State* L, int objindex);
    int (*Lua_getmetatable)(lua_State* L, int objindex);
 
    // Auxiliary library functions (LuaL_ prefix to avoid macro conflicts)
    int (*LuaL_newmetatable)(lua_State* L, const char* tname);
    void (*LuaL_setmetatable)(lua_State* L, const char* tname);
    void* (*LuaL_checkudata)(lua_State* L, int ud, const char* tname);
    double (*LuaL_checknumber)(lua_State* L, int arg);
    long long (*LuaL_checkinteger)(lua_State* L, int arg);
    const char* (*LuaL_checkstring)(lua_State* L, int arg);
    void (*LuaL_setfuncs)(lua_State* L, const void* l, int nup);  // luaL_Reg*
    void (*LuaL_getmetatable)(lua_State* L, const char* tname);
 
    // ===== World Management =====
 
    World* (*GetWorld)(int32_t index);
 
    int32_t (*GetNumWorlds)();
 
    // ===== Node Operations =====
 
    Node* (*SpawnNode)(World* world, const char* typeName);
 
    void (*DestroyNode)(Node* node);
 
    Node* (*FindNode)(World* world, const char* name);
 
    // ===== Node3D Operations =====
 
    void (*Node3D_GetRotation)(Node3D* node, float* outX, float* outY, float* outZ);
 
    void (*Node3D_SetRotation)(Node3D* node, float x, float y, float z);
 
    void (*Node3D_AddRotation)(Node3D* node, float x, float y, float z);
 
    void (*Node3D_GetPosition)(Node3D* node, float* outX, float* outY, float* outZ);
 
    void (*Node3D_SetPosition)(Node3D* node, float x, float y, float z);
 
    void (*Node3D_GetScale)(Node3D* node, float* outX, float* outY, float* outZ);
 
    void (*Node3D_SetScale)(Node3D* node, float x, float y, float z);
 
    // ===== Asset System =====
 
    Asset* (*LoadAsset)(const char* name);
 
    Asset* (*FetchAsset)(const char* name);
 
    void (*UnloadAsset)(const char* name);
 
    // ===== TinyLLM =====
 
    int32_t (*TinyLLM_Encode)(Asset* model, const char* text, bool addBos, bool addEos,
                              int32_t* outTokens, int32_t maxTokens);
 
    int32_t (*TinyLLM_Decode)(Asset* model, int32_t prevToken, int32_t token,
                              char* outStr, int32_t maxLen);
 
    // ===== Audio =====
 
    void (*PlaySound2D)(SoundWave* sound, float volume, float pitch);
 
    void (*StopAllSounds)();
 
    void (*SetMasterVolume)(float volume);
 
    float (*GetMasterVolume)();
 
    // ===== Streaming audio =====
    //
    // Push-based PCM output for addons that decode audio at runtime (e.g. VideoPlayer).
    // See Audio.h for the underlying AUD_* primitives; these are thin forwarders so addons
    // don't have to link the engine's audio symbols directly.
    //
    // Not implemented on all platforms — Audio_OpenStream returns 0 on Linux / 3DS / Android /
    // Dolphin, and addons must treat 0 as "streaming audio unavailable; play video-only".
 
    uint32_t (*Audio_OpenStream)(uint32_t sampleRate, uint32_t numChannels, uint32_t bitsPerSample);
    void     (*Audio_CloseStream)(uint32_t streamId);
    int32_t  (*Audio_SubmitStreamBuffer)(uint32_t streamId, const uint8_t* data, uint32_t byteSize);
    uint64_t (*Audio_GetStreamPlayedSamples)(uint32_t streamId);
    void     (*Audio_SetStreamVolume)(uint32_t streamId, float volume);
    void     (*Audio_SetStreamPaused)(uint32_t streamId, bool paused);
    // Discard any queued buffers without waiting for playback to finish. Use on seek/loop
    // so stale audio doesn't keep playing while new decoded audio catches up.
    // SamplesPlayed does NOT reset (XAudio2 limitation); the addon is expected to snapshot
    // it right after Flush and treat subsequent readings as deltas.
    void     (*Audio_FlushStream)(uint32_t streamId);
 
    // ===== Input =====
 
    bool (*IsKeyDown)(int32_t key);
 
    bool (*IsKeyJustPressed)(int32_t key);
 
    bool (*IsKeyJustReleased)(int32_t key);
 
    bool (*IsMouseButtonDown)(int32_t button);
 
    bool (*IsMouseButtonJustPressed)(int32_t button);
 
    void (*GetMousePosition)(int32_t* x, int32_t* y);
 
    void (*GetMouseDelta)(int32_t* deltaX, int32_t* deltaY);
 
    int32_t (*GetScrollWheelDelta)();
 
    // ===== Time =====
 
    float (*GetDeltaTime)();
 
    float (*GetElapsedTime)();
 
    // ===== Gizmos =====
 
    void (*Gizmos_SetColor)(float r, float g, float b, float a);
 
    void (*Gizmos_SetMatrix)(const float* matrix16);
 
    void (*Gizmos_ResetState)();
 
    void (*Gizmos_DrawCube)(float cx, float cy, float cz, float sx, float sy, float sz);
 
    void (*Gizmos_DrawWireCube)(float cx, float cy, float cz, float sx, float sy, float sz);
 
    void (*Gizmos_DrawSphere)(float cx, float cy, float cz, float radius);
 
    void (*Gizmos_DrawWireSphere)(float cx, float cy, float cz, float radius);
 
    void (*Gizmos_DrawLine)(float x0, float y0, float z0, float x1, float y1, float z1);
 
    void (*Gizmos_DrawRay)(float ox, float oy, float oz, float dx, float dy, float dz);
 
    // ===== Editor UI Hooks (Editor builds only) =====
 
    EditorUIHooks* editorUI;
 
    void (*GetImGuiContext)(ImGuiPluginContext* outCtx);
};