Courage.UI#

require("Courage.UI") opens and closes CReact UI from mods. A panel (creact/panel.bundle.js) opens in the in-game menu host. A popup (creact/popup.bundle.js) draws on top of gameplay without opening the menu. The game registers this module on the shared Luau VM at startup (before any mod entry file runs).

For CReact primitives and layout, see the CReact guide. Panel layout, TSX source, and the compile step are in User Interfaces with CReact.

Loading the module#

local UI = require("Courage.UI")

import * as UI from "Courage.UI"

Discovery#

At mod load, the engine scans each enabled mod folder for CReact bundles:

The mod folder name becomes the id passed to UI.show / UI.showPopup. Panel bundles register with globalThis.__cr_mod_register. Popup bundles use globalThis.__cr_mod_register_popup. The mod UI compiler emits both calls for you.

If a mod has creact/panel.tsx or creact/popup.tsx but no matching bundle, the game logs a warning at scan time. Build bundles before shipping or before testing locally.

Panels vs popups#

UI.setState and UI.getState work the same for both. A mod may ship a panel, a popup, or both under the same mod id.

API#

Luau and panel interop#

Panels receive three props from the host: modId, state, and emit.

Panel clicks run on the UI thread. When the panel dispatches mod-ui/emit, the game forwards the action to Luau immediately and runs Petrichor.Events listeners on the main Luau thread. The overlay also re-queries mod-ui/state after each emit so the panel updates even if a push event is missed.

Panel source is always TSX. Luau drives the panel through Courage.UI and Petrichor.Events.

-- Panel markup is TSX. Import types only in creact/panel.tsx or popup.tsx.

import type { ModUiPanelProps } from "Courage.ModUi"

Usage notes#

• modId must match the mod directory name and the id registered inside panel.bundle.js or popup.bundle.js.
• Calling UI.show or UI.showPopup from init() before the menu host exists is safe. The request is queued and replayed once the UI is ready.
• UI.show / UI.showPopup do not compile TSX. Sources under creact/ are built when you run the game UI build or bun run compile-mod-ui in pc/ui.
• Only one menu panel is active at a time. A second UI.show replaces the visible panel.
• Only one popup overlay is active at a time. A second UI.showPopup replaces the visible popup.
• A popup can show during gameplay. It does not require the menu to be open.

Minimal example#

local Log = require("Petrichor.Log")
local UI = require("Courage.UI")

local HelloUi = mod("hello-ui")

function HelloUi:init()
    Log.info("hello-ui", "opening panel")
    UI.show("hello-ui")
end

function HelloUi:shutdown()
    UI.hide()
end

return HelloUi

import * as Log from "Petrichor.Log"
import * as UI from "Courage.UI"

declare function mod(name: string): any

const HelloUi = mod("hello-ui")

HelloUi.init = function () {
    Log.info("hello-ui", "opening panel")
    UI.show("hello-ui")
}

HelloUi.shutdown = function () {
    UI.hide()
}

export = HelloUi

Listing panels#

local UI = require("Courage.UI")

for _, panel in ipairs(UI.list()) do
    print(panel.modId, panel.title)
end

import * as UI from "Courage.UI"

for (const panel of UI.list()) {
    print(panel.modId, panel.title)
}

Counter with Luau-owned state#

local Events = require("Petrichor.Events")
local UI = require("Courage.UI")

local HelloUi = mod("hello-ui")

function HelloUi:init()
    UI.setState("hello-ui", { count = 0 })
    Events.on("hello-ui:increment", function()
        local state = UI.getState("hello-ui")
        state.count = (state.count or 0) + 1
        UI.setState("hello-ui", state)
    end)
    UI.show("hello-ui")
end

return HelloUi

import * as Events from "Petrichor.Events"
import * as UI from "Courage.UI"

declare function mod(name: string): any

const HelloUi = mod("hello-ui")

HelloUi.init = function () {
    UI.setState("hello-ui", { count: 0 })
    Events.on("hello-ui:increment", () => {
        const state = UI.getState("hello-ui") as { count?: number }
        state.count = (state.count ?? 0) + 1
        UI.setState("hello-ui", state)
    })
    UI.show("hello-ui")
}

export = HelloUi

Panel (creact/panel.tsx)

-- Luau logic is in the tabbed example above. Panel markup is TSX:

import type { ModUiPanelProps } from "Courage.ModUi";

export const title = "Hello from my mod";

export default function Panel({ state, emit }: ModUiPanelProps) {
  const count = (state.count as number) ?? 0;
  return (
    <box role="button" onClick={() => emit("increment")}>
      <text>Clicked {count} times</text>
    </box>
  );
}

Settings panels#

For generator-style option screens, define a schema and push defaults through UI.setState using Courage.Settings (defaults, validate, toUiState).