feat(ex): TypeScriptToLua

This shows how to make use of https://typescripttolua.github.io/ in an
Usagi game to write your code with TypeScript, which then transpiles
to Lua.

Author: brettchalupa

examples/transpile/ts_to_lua/.gitignore

@@ -0,0 +1,4 @@
+# ignore outputted Lua
+*.lua
+node_modules
+package-lock.json

examples/transpile/ts_to_lua/README.md

@@ -0,0 +1,49 @@
+# TypeScriptToLua Usagi Example
+
+An example showing how to use TypeScript with Usagi Engine by transpiling it to
+Lua. Includes updating, drawing, shape primitive, text, and importing exported
+TS functions.
+
+Using https://typescripttolua.github.io/
+
+Requires Node.js to be installed.
+
+Install the package and its CLI:
+
+```
+npm install -D typescript typescript-to-lua
+```
+
+Compile your TypeScript to Lua:
+
+```
+npx tstl
+```
+
+## Using with Usagi's Dev Mode
+
+Start the transpiler in watch mode:
+
+```
+npm run dev:tstl
+```
+
+Start Usagi's dev mode:
+
+```
+npm run dev:usagi
+```
+
+Export your game:
+
+```
+npm run export
+```
+
+## Things Worth Knowing
+
+Look at `./main.ts` to see how to structure your code. Usagi relies on globals,
+so https://typescripttolua.github.io/docs/assigning-global-variables is followed
+by declaring the `_config`, `_update`, and `_draw` functions. It'd be nice if
+there were typedefs for Usagi, but for now, it has to be done manually. This
+would be a good community contribution. There are a few typedefs to get started.

examples/transpile/ts_to_lua/greet.ts

@@ -0,0 +1,3 @@
+export default function greet(this: void, name: string): string {
+  return `Hello, ${name}`;
+}

examples/transpile/ts_to_lua/main.ts

@@ -0,0 +1,62 @@
+/************** Bare minimum type declarations for this example *************/
+
+declare var _config: (this: void) => Record<string, string | number | boolean>;
+declare var _update: (this: void, dt: number) => void;
+declare var _draw: (this: void, dt: number) => void;
+
+/** @noSelf **/
+declare interface InputInterface {
+  RIGHT: number;
+  LEFT: number;
+  held: (btn: number) => boolean;
+}
+/** @noSelf **/
+declare interface GfxInterface {
+  rect_fill: (
+    x: number,
+    y: number,
+    w: number,
+    h: number,
+    color: number,
+  ) => void;
+  text: (
+    text: string,
+    x: number,
+    y: number,
+    color: number,
+  ) => void;
+  COLOR_WHITE: number;
+  COLOR_BLACK: number;
+  clear: (color: number) => void;
+}
+declare const input: InputInterface;
+declare const gfx: GfxInterface;
+
+import greet from "./greet";
+
+let state = {
+  x: 10,
+  y: 40,
+};
+_config = () => {
+  return { game_width: 240, game_height: 240, name: "TS to Lua" };
+};
+
+_update = (dt: number) => {
+  // px/sec
+  let spd = 100;
+  if (input.held(input.LEFT)) {
+    state.x -= spd * dt;
+  }
+
+  if (input.held(input.RIGHT)) {
+    state.x += spd * dt;
+  }
+};
+
+_draw = (dt: number) => {
+  gfx.clear(gfx.COLOR_BLACK);
+  gfx.rect_fill(state.x, state.y, 16, 16, gfx.COLOR_WHITE);
+
+  gfx.text(greet("Alucard"), 4, 4, gfx.COLOR_WHITE);
+};

examples/transpile/ts_to_lua/package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "scripts": {
+    "build": "tstl",
+    "dev:tstl": "tstl --watch",
+    "dev:usagi": "usagi dev",
+    "export": "npm run build && usagi export"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "typescript-to-lua": "^1.37.0"
+  }
+}

examples/transpile/ts_to_lua/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://raw.githubusercontent.com/TypeScriptToLua/TypeScriptToLua/master/tsconfig-schema.json",
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "types": [],
+    "strict": true
+  },
+  "tstl": {
+    "luaTarget": "5.5"
+  }
+}