From edc77437f7ccdbf536134bf294fb065f0d7344ce Mon Sep 17 00:00:00 2001 From: Nathan Bolton Date: Mon, 5 Aug 2024 17:00:56 +0000 Subject: [PATCH] feat: add a Defold API page (#32) * fix: clarify value of lua target * fix: simpler, more clear language * feat: add page on defold API * fix: re-add mention of prettier * feat: finish API page * chore: update desc of export plugin to current --- content/configuration/def-api.md | 58 +++++++++++++++++++++++++ content/configuration/def-extensions.md | 5 +-- content/configuration/plugins.md | 19 +++----- content/configuration/ts-config.md | 2 +- content/index.mdx | 1 + 5 files changed, 69 insertions(+), 16 deletions(-) create mode 100644 content/configuration/def-api.md diff --git a/content/configuration/def-api.md b/content/configuration/def-api.md new file mode 100644 index 0000000..0f9f655 --- /dev/null +++ b/content/configuration/def-api.md @@ -0,0 +1,58 @@ +--- +title: "Defold API" +order: 3 +--- + +Getting accurate types for the Defold API is an important part of ts-defold. Here are some +ways to get the definitions you need: + +:sparkles: The `types` library is built-in into all ts-defold templates, and is automatically +published to keep up with the latest changes to Defold. + +:star2: [TS-Defold Types II](https://github.com/thinknathan/ts-defold-types) +is a drop-in alternative for the `types` library, with hand-written patches to provide for +more accurate and useful types. + +:boom: [Defold Annotations for Typescript](https://github.com/elMuso/defold-annotations-typescript/) +Is a tool for generating types based on the Defold API, with more accurate types and better coverage +of Lua features than the default `types`. + +# Working with Messages + +The Defold engine is built around communication using [messages](https://defold.com/manuals/message-passing/), +so it helps to have accurate definitions of the built-in messages. + +:notes: [Utility Types](https://github.com/thinknathan/tsd-util-types/tree/main/types) +include messages. + +:boom: [Defold Annotations for Typescript](https://github.com/elMuso/defold-annotations-typescript/) +can generate a definitions file with Defold's built-in messages. + +# Working with Vector Math + +TypeScript doesn't have a built-in way to understand the resulting type of +an operation involving vectors. + +```ts +const result = go.get_position() + vmath.vector3(1, 1, 1); // type: number ?!?? +``` + +If you're confident about the result, you can cast the type: + +```ts +const result = (go.get_position() + vmath.vector3(1, 1, 1)) as vmath.vector3; // type: vmath.vector3 +``` + +Or you can use the +[Operator Map Types](https://typescripttolua.github.io/docs/advanced/language-extensions#operator-map-types) +provided by TSTL to enable full type checking. + +:notes: [Utility Types](https://github.com/thinknathan/tsd-util-types/blob/main/types/vmath.d.ts) +include all relevant vector math operations. + +```ts +namespace vmath { + export const add: LuaAddition; +} +const result = vmath.add(go.get_position(), vmath.vector3(1, 1, 1)) // type: vmath.vector3 +``` diff --git a/content/configuration/def-extensions.md b/content/configuration/def-extensions.md index 0905ebc..fea0489 100644 --- a/content/configuration/def-extensions.md +++ b/content/configuration/def-extensions.md @@ -1,6 +1,6 @@ --- title: "Defold Extensions" -order: 3 +order: 4 --- Defold is a modular engine, with a ton of functionality available through @@ -24,5 +24,4 @@ and generate types automagically. # Write Your Own -If all else fails, you can read the documentation and write your own types. -Your preferred AI tool (like Chat-GPT) may also be able to help get you most of the way there. +If all else fails, you can write your own types by hand, or ask an AI tool to help. diff --git a/content/configuration/plugins.md b/content/configuration/plugins.md index 4795f6f..9907e66 100644 --- a/content/configuration/plugins.md +++ b/content/configuration/plugins.md @@ -7,27 +7,22 @@ order: 2 ## Export Globals -The [@ts-defold/tstl-export-as-global](https://github.com/ts-defold/tstl-export-as-global) +The [tstl-export-to-global](https://github.com/thinknathan/tstl-export-to-global) plugin is used to allow the export function to emulate the expected behavior of "exports" in a Defold game script. The `init`, `on_input`, `on_message`, `on_reload`, `update`, and `final` functions are executed on each game script by the Defold game engine. Each of those functions -are expected to be defined in the file scope of the game script in order for the -game engine to execute them. +are expected to be defined in the file scope of the game script for the game engine +to execute them. -In order to adhere to these requirements, the ***tstl-export-as-global*** plugin -will look for any exported function that matches a `globals: { functions: [] }` array -defined in the `.tsconfig.json` plugin configuration options, and hoist them to the global -scope of the file. +To adhere to these requirements, the ***tstl-export-to-global*** plugin will hoist +all exports to the global scope of the file. ```json { - "name": "@ts-defold/tstl-export-as-global", - "match": ".*script.ts$", - "globals": { - "functions": [ "init", "on_input", "on_message", "on_reload", "update", "final" ] - } + "name": "tstl-export-to-global", + "match": ".*\\..*script.ts$" } ``` diff --git a/content/configuration/ts-config.md b/content/configuration/ts-config.md index 7f521ae..05036f4 100644 --- a/content/configuration/ts-config.md +++ b/content/configuration/ts-config.md @@ -30,7 +30,7 @@ These options are of particular concern: - `"luaTarget": "5.1"` - Defold recommends targeting Lua 5.1 for the broadest support of deployment targets. If you do not want to release your game on an HTML5 target, you may want to modify -this to bring in [additional syntax features](https://typescripttolua.github.io/docs/caveats). +the value to `"JIT"` to bring in [additional syntax features](https://typescripttolua.github.io/docs/caveats). - `"luaLibImport": "require"` - This setting is used to generate the `lualib_bundle.lua` and then insert a require statement at the top of each script to bring in the diff --git a/content/index.mdx b/content/index.mdx index 5725277..ec6dc5e 100644 --- a/content/index.mdx +++ b/content/index.mdx @@ -23,6 +23,7 @@ your [Defold](https://defold.com) game projects. - Typings and auto-complete for the [Defold API](https://defold.com/ref/stable/go/) - Project generator and project templates for a quick start - ESLint configured and ready to _lint_ your code +- Prettier auto-formatting included - Type generator that stays up to date with the Defold _API_ - Library of types for Defold native extensions and Lua libraries - Debugging with sourcemaps