Skip to content

type-stubs.md

Latest commit

 

History

History
134 lines (99 loc) · 9 KB

type-stubs.md

File metadata and controls

134 lines (99 loc) · 9 KB
Raw

Type stubs

Summary

The build generates Luau type stubs for the game bindings. They give autocomplete and type checks in your editor. This page describes the stub file and the overload policy. For download, placement, and LSP setup, see Editor setup.

What the stubs are

The code generator creates types/geode.d.luau, describing all classes, factories, enums, and the geode namespace. Do not edit this file by hand.

The build output is one file. Source files under extra_bindings are inputs, never shipped separately.

-- Excerpt of types/geode.d.luau
declare task: TaskNamespace          -- Global libraries use declare.
export type LoaderModInfo = { ... }  -- Support types use export type.

A taste of what you get:

local info = geode.Loader.getAllMods()[1]
print(info.id) -- Typed as string by LoaderModInfo.

Every file in tools/luau_codegen/extra_bindings/ is appended to the same output at build time:

Stub file Adds Doc page
task.dluau task, time, loadstring, warn tasks and time, globals
imgui.dluau imgui imgui
web.dluau WebNamespace and request and response types web
hook.dluau HookHandle, HookCallbackTable hooks
mod.dluau ModNamespace mod
loader.dluau LoaderModInfo, LoaderNamespace loader
json.dluau JsonNamespace json
keyboard.dluau keyboard input support types Keyboard input
mouse.dluau mouse input support types Mouse input
fs.dluau FsRoot, FsNamespace fs
gd3d.dluau gd3d, Gd3dTransform, Gd3dMesh, Gd3dMaterial, Gd3dTexture, Gd3dViewportFrame gd3d
websocket.dluau websocket and connection and server types websocket
color.dluau Geode color support types cocos
popup.dluau managed popup support types UI and layouts
lunar.dluau lunar, LunarRig, LunarAnimationDef, LunarAnimationTrack lunar

Files for a global like task use declare. Files that only add support types use export type.

Manual free-function fields

Handwritten bindings that codegen does not scan are listed in MANUAL_FREE_FN_FIELDS inside tools/luau_codegen/emit/luau_types/manual_fields.py. The generator merges these entries into types/geode.d.luau so stubs stay complete.

Namespaces covered today:

  • web field on geode.utils (runtime namespace geode.utils.web)
  • geode.utils.base64 and geode.utils.permission
  • geode.ColorProvider, geode.VersionInfo, geode.Keybind, and keyboard input namespaces
  • geode.Color, geode.PopupManager, and geode.utils.random.choice
  • Selected geode.cocos color helpers

Codegen free-function namespaces

Codegen scans Geode headers listed in tools/luau_codegen/model/free_fn_sources.py and merges the results into types/geode.d.luau. These are not in MANUAL_FREE_FN_FIELDS.

Namespace Source header Doc page
geode.utils (top-level) utils/general.hpp geode.utils
geode.utils.clipboard utils/general.hpp geode.utils
geode.utils.game utils/general.hpp game
geode.utils.platform utils/general.hpp geode.utils
geode.utils.thread utils/general.hpp geode.utils
geode.utils.string utils/string.hpp geode.utils
geode.utils.random utils/random.hpp geode.utils
geode.cocos (codegen portion) utils/cocos.hpp cocos
geode UI free functions ui/Popup.hpp, ui/GeodeUI.hpp, ui/General.hpp UI and layouts

Generated support types can also appear in the stub. GeodeTaskHandle<T> represents a native Geode async task returned by generated bindings. It has onComplete, cancel, detach, isPending, isDone, and isDetached. It is separate from the TaskHandle returned by the Lua task library.

Some Geode C++ wide integer types (size_t, uint64_t, and similar) appear as string in the stub. At runtime, pass decimal integer strings for those arguments and read wide integer results as decimal strings.

Return pointers use ? in stubs. Arg pointers do not. Nil object args fail unless hook allow_nil_object. See hooks.

Container field and argument shapes are summarized in Game objects. Pair, nested, and ccCArray binding details live under Codegen.

tests/luau_codegen/guards/test_manual_fields_sync.py guards drift between the Python map, C++ registrars, and emitted stubs.

Enums

Enum stubs use a number alias plus a FooNamespace table type for constants. See enums.

Overloaded members

Methods and factories with several overloads are emitted as one widened signature that ends in ...any. Leading arguments are typed where every overload agrees, then the rest fall back to ...any. Runtime picks overload by arity only. One Lua key per C++ name. See Codegen.

Luau keyword method names

Codegen-exported methods with Luau keyword names get a ToLua suffix in stubs and runtime. See Codegen.

Regenerating the stub

Building LuauAPI runs the luauapi_codegen target and refreshes types/geode.d.luau. See Codegen and Editor setup.

Related

Source

  • .luaurc
  • tools/luau_codegen/emit/luau_types/
  • tools/luau_codegen/extra_bindings/
  • CMakeLists.txt