Native UI

Group ui · 62 exports · from forks/gamexueren/scripthook.h (framework 1.0-beta7-wildm1, SH_API_VERSION 2)

Engine widgets in scenes of our own; see docs/ui.md.

Export	Summary
ShUiReady	1 once the world is up; poll before building.
ShUiEnable	Kill switch, on by default.
ShUiSetDefaultFont	Font and plate texture for new widgets, by asset GUID ("873fe53f-3b90-db4d-9887-d3cc6edeaba9", storage order).
ShUiSetDefaultImage	See ShUiSetDefaultFont.
ShUiGen	Changes when the scene reloads; older ids are dead.
ShSceneHandle	The phoenix::Scene handle that hosts every ShUi widget, built and driven by the DLL itself; 0 until in game.
ShUiPanel	A container with a translucent quad behind it.
ShUiLabel	A line of text in the HUD font.
ShUiImage	A tinted quad, for bars and highlights.
ShUiSetText	—
ShUiSetPos	—
ShUiSetSize	—
ShUiSetColour	—
ShUiSetAlpha	—
ShUiShow	Hiding a panel hides its children too.
ShUiDestroy	Detaches the widget and its children from the tree.
ShUiCreate	Any widget under any container (0 = the scene root), at any depth.
ShUiPropType	0 when the widget's class has no such property.
ShUiSetF	Every one of these is one round trip to the game thread: the write is queued and the caller waits for it (up to JOB_WAIT_MS, 3s).
ShUiSetU	See ShUiSetF.
ShUiSetV	See ShUiSetF.
ShUiSetS	See ShUiSetF.
ShUiGetF	See ShUiSetF.
ShUiGetU	See ShUiSetF.
ShUiGetV	See ShUiSetF.
ShUiGetS	See ShUiSetF.
ShUiSetAutoSize	Label size follows its text on the axes set to 1.
ShUiMeasure	The label's laid out box: its text bounds once an axis is automatic, otherwise the size that was set.
ShUiTextureCreate	RGBA8 pixels to an engine texture, stride in bytes.
ShUiImageSet	Shows a texture on an image widget or panel plate.
ShUiPropCount	The resolved property records: class, id, type.
ShUiPropAt	See ShUiPropCount.
ShUiSceneCreate	Scenes: layers of your own.
ShUiSceneSetOrder	See ShUiSceneCreate.
ShUiSceneShow	See ShUiSceneCreate.
ShUiSceneDestroy	Every widget of the scene, then the scene.
ShUiCreateIn	A widget in a scene; parent 0 is that scene's root.
fn	After a world reload, once the scene is back: the old widgets are gone, rebuild inside.
ShUiBegin	Edits between Begin and Commit run as one job.
ShUiCommit	See ShUiBegin.
ShUiAbort	See ShUiBegin.
done	Commit from a worker; done(ok, user) when it landed.
ShUiReparent	Tree: move a widget under another container of the same scene at a sibling index (draw order); list children.
ShUiChildCount	See ShUiReparent.
ShUiChildAt	See ShUiReparent.
ShUiSetInput	—
ShUiFocus	—
ShUiFocused	—
ShUiInputWatch	Declare that a virtual key needs event polling (1) or withdraw it (0).
ShBlockKey	One virtual key hidden from the game until released.
ShCaptureKeys	Every key but the escapes hidden, focus uses this.
ShGameFocused	Is the game's own window the one in front?
ShFakeKey	Queue full press/release taps of a virtual key into the game's DirectInput keyboard reports.
ShFakeKeyFast	Same, but phases advance per GetState report with no wall-clock delay, so N taps burst as fast as the engine polls the device.
ShFakeKeyBusy	1 while a fake-key tap sequence is still in flight.
ShKeyState	Diag: what the game last saw on this keyboard device, or -1 before any report was captured.
ShGameSceneActive	1 when a scene of that name was drawn last frame.
ShGameScenes	Comma separated names drawn last frame; the count.
ShGameHudShow	Show or suppress the game-owned HUD_* scenes.
ShGameHudSceneShow	—
ShGameHudSceneVisible	What the renderer will do for this scene right now.
ShGameHudScenes	The HUD_* scenes drawn last frame, comma separated; returns the count.

ShUiReady

SH_API int      ShUiReady(void);

1 once the world is up; poll before building. It also fires the reset callbacks after a world reload.

scripthook.h, line 3144

ShUiEnable

SH_API void     ShUiEnable(int on);

Kill switch, on by default.

scripthook.h, line 3146

ShUiSetDefaultFont

SH_API int      ShUiSetDefaultFont(const char *guid);

Font and plate texture for new widgets, by asset GUID ("873fe53f-3b90-db4d-9887-d3cc6edeaba9", storage order). Defaults: the HUD font and the white 16x16 texture.

scripthook.h, line 3150

ShUiSetDefaultImage

SH_API int      ShUiSetDefaultImage(const char *guid);

Documented together with ShUiSetDefaultFont just above.

scripthook.h, line 3151

ShUiGen

SH_API int      ShUiGen(void);

Changes when the scene reloads; older ids are dead.

scripthook.h, line 3153

ShSceneHandle

SH_API uint64_t ShSceneHandle(void);

The phoenix::Scene handle that hosts every ShUi widget, built and driven by the DLL itself; 0 until in game.

scripthook.h, line 3156

ShUiPanel

SH_API uint32_t ShUiPanel(float x, float y, float w, float h,
                          uint32_t rgb, float alpha);

A container with a translucent quad behind it.

scripthook.h, line 3159

ShUiLabel

SH_API uint32_t ShUiLabel(uint32_t panel, float x, float y, float w,
                          float h, const char *text, uint32_t rgb);

A line of text in the HUD font. panel 0 is the root.

scripthook.h, line 3162

ShUiImage

SH_API uint32_t ShUiImage(uint32_t panel, float x, float y, float w,
                          float h, uint32_t rgb, float alpha);

A tinted quad, for bars and highlights.

scripthook.h, line 3165

ShUiSetText

SH_API int  ShUiSetText(uint32_t id, const char *text);

No doc comment in the header.

scripthook.h, line 3168

ShUiSetPos

SH_API int  ShUiSetPos(uint32_t id, float x, float y);

No doc comment in the header.

scripthook.h, line 3169

ShUiSetSize

SH_API int  ShUiSetSize(uint32_t id, float w, float h);

No doc comment in the header.

scripthook.h, line 3170

ShUiSetColour

SH_API int  ShUiSetColour(uint32_t id, uint32_t rgb);

No doc comment in the header.

scripthook.h, line 3171

ShUiSetAlpha

SH_API int  ShUiSetAlpha(uint32_t id, float alpha);

No doc comment in the header.

scripthook.h, line 3172

ShUiShow

SH_API int  ShUiShow(uint32_t id, int visible);

Hiding a panel hides its children too.

scripthook.h, line 3174

ShUiDestroy

SH_API int  ShUiDestroy(uint32_t id);

Detaches the widget and its children from the tree.

scripthook.h, line 3176

ShUiCreate

SH_API uint32_t ShUiCreate(uint32_t parent, int cls, float x, float y,
                           float w, float h);

Any widget under any container (0 = the scene root), at any depth. Text, colour, alpha, UVs and the rest go through the property calls below.

scripthook.h, line 3216

ShUiPropType

SH_API int  ShUiPropType(uint32_t id, uint32_t prop);

0 when the widget's class has no such property.

scripthook.h, line 3220

ShUiSetF

SH_API int  ShUiSetF(uint32_t id, uint32_t prop, float v);

Every one of these is one round trip to the game thread: the write is queued and the caller waits for it (up to JOB_WAIT_MS, 3s). Fine once per action, wasteful in a loop - a row of twenty controls is twenty round trips. ShUiBegin/ShUiCommit below batch them into one, and that is the intended way to build or refresh a page.

Do not call from a frame callback or from the game thread: the wait can only end when that thread runs the queue, which it cannot do while the callback is still inside.

scripthook.h, line 3230

ShUiSetU

SH_API int  ShUiSetU(uint32_t id, uint32_t prop, uint32_t v);

Documented together with ShUiSetF just above.

scripthook.h, line 3231

ShUiSetV

SH_API int  ShUiSetV(uint32_t id, uint32_t prop, const float *v, int n);

Documented together with ShUiSetF just above.

scripthook.h, line 3232

ShUiSetS

SH_API int  ShUiSetS(uint32_t id, uint32_t prop, const char *utf8);

Documented together with ShUiSetF just above.

scripthook.h, line 3233

ShUiGetF

SH_API int  ShUiGetF(uint32_t id, uint32_t prop, float *out);

Documented together with ShUiSetF just above.

scripthook.h, line 3234

ShUiGetU

SH_API int  ShUiGetU(uint32_t id, uint32_t prop, uint32_t *out);

Documented together with ShUiSetF just above.

scripthook.h, line 3235

ShUiGetV

SH_API int  ShUiGetV(uint32_t id, uint32_t prop, float *out, int n);

Documented together with ShUiSetF just above.

scripthook.h, line 3236

ShUiGetS

SH_API int  ShUiGetS(uint32_t id, uint32_t prop, char *out, int n);

Documented together with ShUiSetF just above.

scripthook.h, line 3237

ShUiSetAutoSize

SH_API int  ShUiSetAutoSize(uint32_t id, int autoW, int autoH);

Label size follows its text on the axes set to 1.

scripthook.h, line 3239

ShUiMeasure

SH_API int  ShUiMeasure(uint32_t id, float *w, float *h);

The label's laid out box: its text bounds once an axis is automatic, otherwise the size that was set.

scripthook.h, line 3242

ShUiTextureCreate

SH_API uint32_t ShUiTextureCreate(int w, int h, const uint8_t *rgba,
                                  int stride);

RGBA8 pixels to an engine texture, stride in bytes. Returns an id, 0 on failure; lives for the session.

scripthook.h, line 3246

ShUiImageSet

SH_API int  ShUiImageSet(uint32_t id, uint32_t texture);

Shows a texture on an image widget or panel plate.

scripthook.h, line 3249

ShUiPropCount

SH_API int  ShUiPropCount(void);

The resolved property records: class, id, type.

scripthook.h, line 3251

ShUiPropAt

SH_API int  ShUiPropAt(int i, char *cls, int n, uint32_t *prop,
                       int *type);

Documented together with ShUiPropCount just above.

scripthook.h, line 3252

ShUiSceneCreate

SH_API uint32_t ShUiSceneCreate(const char *name, int order);

Scenes: layers of your own. Scene 1 is the default. Order below 0 draws under the game's UI, the rest over it, lowest first.

scripthook.h, line 3258

ShUiSceneSetOrder

SH_API int      ShUiSceneSetOrder(uint32_t scene, int order);

Documented together with ShUiSceneCreate just above.

scripthook.h, line 3259

ShUiSceneShow

SH_API int      ShUiSceneShow(uint32_t scene, int visible);

Documented together with ShUiSceneCreate just above.

scripthook.h, line 3260

ShUiSceneDestroy

SH_API int      ShUiSceneDestroy(uint32_t scene);

Every widget of the scene, then the scene.

scripthook.h, line 3262

ShUiCreateIn

SH_API uint32_t ShUiCreateIn(uint32_t scene, uint32_t parent, int cls,
                             float x, float y, float w, float h);

A widget in a scene; parent 0 is that scene's root.

scripthook.h, line 3264

fn

SH_API int      ShUiSetReset(uint32_t scene,
                             void (*fn)(uint32_t scene, void *user),
                             void *user);

Exported variable.

After a world reload, once the scene is back: the old widgets are gone, rebuild inside.

scripthook.h, line 3268

ShUiBegin

SH_API int      ShUiBegin(void);

Edits between Begin and Commit run as one job. Creates and reads still run at once. Per thread.

scripthook.h, line 3273

ShUiCommit

SH_API int      ShUiCommit(void);

Documented together with ShUiBegin just above.

scripthook.h, line 3274

ShUiAbort

SH_API int      ShUiAbort(void);

Documented together with ShUiBegin just above.

scripthook.h, line 3275

done

SH_API int      ShUiCommitAsync(void (*done)(int ok, void *user),
                                void *user);

Exported variable.

Commit from a worker; done(ok, user) when it landed.

scripthook.h, line 3277

ShUiReparent

SH_API int      ShUiReparent(uint32_t id, uint32_t parent, int index);

Tree: move a widget under another container of the same scene at a sibling index (draw order); list children.

scripthook.h, line 3282

ShUiChildCount

SH_API int      ShUiChildCount(uint32_t id);

Documented together with ShUiReparent just above.

scripthook.h, line 3283

ShUiChildAt

SH_API uint32_t ShUiChildAt(uint32_t id, int index);

Documented together with ShUiReparent just above.

scripthook.h, line 3284

ShUiSetInput

SH_API int      ShUiSetInput(uint32_t scene, ShUiInputFn fn, void *user);

No doc comment in the header.

scripthook.h, line 3295

ShUiFocus

SH_API int      ShUiFocus(uint32_t scene, int take);

No doc comment in the header.

scripthook.h, line 3296

ShUiFocused

SH_API uint32_t ShUiFocused(void);

No doc comment in the header.

scripthook.h, line 3297

ShUiInputWatch

SH_API int      ShUiInputWatch(int vk, int on);

Declare that a virtual key needs event polling (1) or withdraw it (0). While nothing has been declared the poll thread sweeps the whole keyboard, exactly as it always did; once anything is declared it sweeps the declared keys plus every key it is currently holding, and nothing else. Declaring is therefore how a consumer says what it listens for - and a consumer that declares nothing keeps working unchanged.

scripthook.h, line 3304

ShBlockKey

SH_API int      ShBlockKey(int vk, int on);

One virtual key hidden from the game until released.

scripthook.h, line 3306

ShCaptureKeys

SH_API int      ShCaptureKeys(int on);

Every key but the escapes hidden, focus uses this.

scripthook.h, line 3308

ShGameFocused

SH_API int      ShGameFocused(void);

Is the game's own window the one in front? Any window of this process counts, so windowed and borderless fullscreen both answer yes, and a backgrounded game answers no.

Ask this before acting on a key read with GetAsyncKeyState: that reads the PHYSICAL key, so without the check a hotkey fires on a press meant for whichever window the player switched to. One GetForegroundWindow, answered uncached - a stale "yes" is the one case this exists to prevent.

scripthook.h, line 3319

ShFakeKey

SH_API void     ShFakeKey(int vk, int taps);

Queue full press/release taps of a virtual key into the game's DirectInput keyboard reports. The phases advance in real time (60 ms per phase), so the engine sees a human-length press.

scripthook.h, line 3324

ShFakeKeyFast

SH_API void     ShFakeKeyFast(int vk, int taps);

Same, but phases advance per GetState report with no wall-clock delay, so N taps burst as fast as the engine polls the device.

scripthook.h, line 3327

ShFakeKeyBusy

SH_API int      ShFakeKeyBusy(void);

1 while a fake-key tap sequence is still in flight.

scripthook.h, line 3329

ShKeyState

SH_API int      ShKeyState(int vk);

Diag: what the game last saw on this keyboard device, or -1 before any report was captured.

scripthook.h, line 3332

ShGameSceneActive

SH_API int      ShGameSceneActive(const char *name);

1 when a scene of that name was drawn last frame.

scripthook.h, line 3348

ShGameScenes

SH_API int      ShGameScenes(char *buf, int n);

Comma separated names drawn last frame; the count.

scripthook.h, line 3350

ShGameHudShow

SH_API int      ShGameHudShow(int visible);

Show or suppress the game-owned HUD_* scenes. Framework and menu scenes remain visible either way.

scripthook.h, line 3353

ShGameHudSceneShow

SH_API int      ShGameHudSceneShow(const char *name, int visible);

No doc comment in the header.

scripthook.h, line 3360

ShGameHudSceneVisible

SH_API int      ShGameHudSceneVisible(const char *name);

What the renderer will do for this scene right now.

scripthook.h, line 3362

ShGameHudScenes

SH_API int      ShGameHudScenes(char *buf, int n);

The HUD_* scenes drawn last frame, comma separated; returns the count.

scripthook.h, line 3364