@defold-typescript/library-types 0.18.1

package/NOTICE

@@ -0,0 +1,52 @@
+@defold-typescript/library-types
+=================================
+
+This package vendors TypeScript type declarations derived from the Lua library
+definitions published by the ts-defold/library project:
+
+    https://github.com/ts-defold/library
+    License: MIT
+    Pinned commit: 2fe3aed3352a913d2859e6e85d34a8b23d821368
+
+The `.d.ts` sources under `generated/` are produced by codemodding the upstream
+declarations — Defold core types (`vmath.*`, `hash`, `url`, engine handles) are
+renamed to the `@defold-typescript/types` surface; all other content is left
+byte-identical. The original copyright and license notices of the upstream
+authors are retained.
+
+Attributed upstream libraries (by their directory in ts-defold/library):
+
+    - monarch             — Britzl, https://github.com/britzl/monarch
+    - defold-orthographic — Britzl, https://github.com/britzl/defold-orthographic
+    - gooey               — Britzl, https://github.com/britzl/gooey
+    - defold-input        — Britzl, https://github.com/britzl/defold-input
+    - platypus            — Britzl, https://github.com/britzl/platypus
+    - defold-event        — Insality, https://github.com/Insality/defold-event
+    - defold-richtext     — Britzl, https://github.com/britzl/defold-richtext
+    - narrator            — astrochili, https://github.com/astrochili/narrator
+    - defcon              — Britzl, https://github.com/britzl/defcon
+    - defold-lang         — Insality, https://github.com/Insality/defold-lang
+    - defold-saver        — Insality, https://github.com/Insality/defold-saver
+    - defsave             — subsoap, https://github.com/subsoap/defsave
+    - library-defold-persist — klaytonkowalski, https://github.com/klaytonkowalski/library-defold-persist
+    - defold-proto        — Insality, https://github.com/Insality/defold-proto
+    - defmath             — subsoap, https://github.com/subsoap/defmath
+    - dicebag             — 8bitskull, https://github.com/8bitskull/dicebag
+    - defold-tweener      — Insality, https://github.com/Insality/defold-tweener
+    - squid               — paweljarosz, https://github.com/paweljarosz/squid
+    - starly              — VowSoftware, https://github.com/VowSoftware/starly
+    - defold-log          — Insality, https://github.com/Insality/defold-log
+    - defold-metrics      — Britzl, https://github.com/britzl/defold-metrics
+    - deftest             — Britzl, https://github.com/britzl/deftest
+    - lua-immutable       — paweljarosz, https://github.com/paweljarosz/lua-immutable
+    - nakama-defold       — Heroic Labs, https://github.com/heroiclabs/nakama-defold
+    - defold-yagames      — indiesoftby, https://github.com/indiesoftby/defold-yagames
+    - defold-bridge       — Playgama, https://github.com/Playgama/bridge-defold
+    - defold-zzfx         — thejustinwalsh, https://github.com/thejustinwalsh/defold-zzfx
+    - boom                — Britzl, https://github.com/britzl/boom
+    - bzAnim              — jbp4444, https://github.com/jbp4444/bzAnim
+    - library-defold-rendy — klaytonkowalski, https://github.com/klaytonkowalski/library-defold-rendy
+
+Each upstream library is distributed under its own license by its original
+author. The ts-defold/library MIT license covers the TypeScript definition
+packaging that this package's `generated/` output is derived from.

package/README.md

@@ -0,0 +1,78 @@
+# @defold-typescript/library-types
+
+Vendored TypeScript type declarations for a curated set of popular Defold Lua
+libraries, core-type-renamed against
+[`@defold-typescript/types`](https://www.npmjs.com/package/@defold-typescript/types).
+
+This is a support package for the
+[`@defold-typescript`](https://github.com/defold-typescript/toolchain) toolchain.
+You normally do not install it directly — it ships as a dependency of
+[`@defold-typescript/cli`](https://www.npmjs.com/package/@defold-typescript/cli),
+which reads it at runtime.
+
+## Why it exists
+
+Many popular Defold libraries are plain Lua, installed through the editor's
+**Fetch Libraries** and carrying no `.script_api`, so there is nothing for the
+CLI's `resolve` command to extract types from. For a curated set of those, this
+package ships hand-vetted, ready-to-use TypeScript declarations.
+
+When `resolve` encounters a declared dependency with no `.script_api`, it matches
+it against this corpus by source identity, verifies the match against the
+downloaded archive's Lua require paths, and materializes the corresponding
+declaration into the project's `.defold-types/libraries/`. The import specifier is
+the Lua `require` path — e.g. `import * as dicebag from 'dicebag.dicebag'` — so it
+matches what Fetch Libraries installs at runtime.
+
+## What's inside
+
+- `generated/<module>.d.ts` — one ambient `declare module '<require-path>'` per
+  vendored module, core-type-renamed to the `@defold-typescript/types` surface.
+- `library-classification.json`, `library-targets.json` — the registries mapping
+  each module to its upstream source and generated path. The CLI reads these to
+  drive matching and materialization.
+- `api-doc/<module>.json` — ref-doc JSON extracted from each declaration, consumed
+  by the documentation site to render per-library API pages.
+- `NOTICE` — upstream attribution for every vendored library.
+
+## Provenance
+
+Declarations are adapted from
+[`ts-defold/library`](https://github.com/ts-defold/library) (MIT) at a pinned
+commit, recorded per module in `library-targets.json`. ts-defold's hand-written
+`declare module` files already model these libraries faithfully; the only surface
+that differs is core-type naming. A codemod (`scripts/sync-library-types.ts`)
+walks the TypeScript AST and rewrites **type references only** — property names,
+JSDoc, `declare module`, and passthrough extensions (`LuaMultiReturn`, `LuaMap`)
+stay byte-identical:
+
+| ts-defold | `@defold-typescript/types` |
+| --------- | -------------------------- |
+| `hash`, `url` | `Hash`, `Url` |
+| `vmath.vector3` / `vmath.vector4` / `vmath.matrix4` / `vmath.quat` | `Vector3` / `Vector4` / `Matrix4` / `Quaternion` |
+| `node`, `texture`, … (engine handles) | `Opaque<"node">`, `Opaque<"texture">`, … |
+
+The renamed names resolve against the ambient globals in `@defold-typescript/types`,
+so no import injection is needed. Any `vmath.*` reference with no mapping is a hard
+error at regeneration time, so a missing rename fails loud rather than degrading to
+`any`. Nothing is authored by hand beyond the source pins, and the committed output
+is guarded against drift in CI.
+
+Regenerate after changing the rename table or re-pinning a source:
+
+```sh
+bun run --filter @defold-typescript/library-types regen
+```
+
+## Direct use
+
+The `exports` map exposes each module under a type-only subpath if you want a
+single library's declarations without the CLI. These are ambient type declarations
+only — there is no runtime code in this package. For the normal workflow, prefer
+letting `@defold-typescript/cli resolve` materialize them for you; see the
+[toolchain docs](https://github.com/defold-typescript/toolchain).
+
+## License
+
+MIT. Vendored declarations retain their upstream authors' licenses, credited in
+`NOTICE`.

package/api-doc/boom.boom.json

@@ -0,0 +1,26 @@
+{
+  "info": {
+    "namespace": "boom.boom",
+    "brief": "Boom is a game framework built on top of Defold.",
+    "description": "Boom is a game framework built on top of Defold."
+  },
+  "elements": [
+    {
+      "type": "FUNCTION",
+      "name": "boom",
+      "brief": "Start a boom game. Call this from your own game script",
+      "description": "Start a boom game. Call this from your own game script",
+      "parameters": [
+        {
+          "name": "game",
+          "doc": "Game loop function",
+          "types": [
+            "() => void"
+          ],
+          "is_optional": "False"
+        }
+      ],
+      "returnvalues": []
+    }
+  ]
+}