Skip to content
Skills Library
Programming · Building & coding

typescript-to-lua-guide

/typescript-to-lua-guide

Use when editing TypeScript that compiles to Lua via TSTL 1.24+ (game scripting, Defold, embedded engines). Triggers on `.ts` files in game/scripting directories with TSTL config, and on prompts about LuaMultiReturn, namespaces, decorators, stable table layouts, or Lua interop boundaries, even when the user doesn't say 'TSTL'.

Repository
platform ↗
Licence
MIT
Last repository change
08.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
14
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when editing TypeScript that compiles to Lua via TSTL 1.24+ (game scripting, Defold, embedded engines). Triggers on `.ts` files in game/scripting directories with TSTL config, and on prompts about LuaMultiReturn, namespaces, decorators, stable table layouts, or Lua interop boundaries, even when the user doesn't say 'TSTL'.

Triggers from the description

t say
Original author description

Use when editing TypeScript that compiles to Lua via TSTL 1.24+ (game scripting, Defold, embedded engines). Triggers on `.ts` files in game/scripting directories with TSTL config, and on prompts about LuaMultiReturn, namespaces, decorators, stable table layouts, or Lua interop boundaries, even when the user doesn't say 'TSTL'.

How it works

  1. Requirements
  2. Essentials
  3. Gotchas
  4. Progressive disclosure
Original SKILL.md headings · 36 lines, 337 words
SKILL.md preview
---
name: typescript-to-lua-guide
description: "Use when editing TypeScript that compiles to Lua via TSTL 1.24+ (game scripting, Defold, embedded engines). Triggers on `.ts` files in game/scripting directories with TSTL config, and on prompts about LuaMultiReturn, namespaces, decorators, stable table layouts, or Lua interop boundaries, even when the user doesn't say 'TSTL'."
---

# TypeScript-to-Lua Coding Guidelines

The output is Lua. For Lua runtime semantics and idioms: module pattern, coroutines, metatables, error handling, string building. Apply **lua-guide**; for hot-path tuning of the generated code apply **lua-opinionated-guide**. This skill covers only the TS→Lua transpiler boundary: what translates, how to shape TS source for clean Lua, and TSTL-specific features.

## Requirements

- TSTL ≥ 1.24; TS strict mode; Lua ≥ 5.3 / LuaJIT 2.1.

## Essentials

- **Code organization** - Favor namespaces/functions over classes for clean Lua output; Lua module idioms in **lua-guide**, see [references/namespaces-vs-classes.md](references/namespaces-vs-classes.md)
- **TSTL features** - Use LuaMultiReturn, decorators when beneficial, see [references/multi-return-functions.md](references/multi-return-functions.md), [references/tstl-decorators.md](references/tstl-decorators.md)
- **Performance** - Keep tables stable, cache lookups, design for Lua GC and coroutines; the JIT "why" is in **lua-opinionated-guide**, see [references/performance-tips.md](references/performance-tips.md), [references/coroutine-patterns.md](references/coroutine-patterns.md)
- **Optimization** - Avoid heavy TypeScript features, see [references/avoiding-heavy-features.md](references/avoiding-heavy-features.md)

## Gotchas

- Not all TypeScript features translate: generators, `for-await-of`, dynamic `import()`, and BigInt are unsupported or partially supported
- Translation is source-to-source; runtime semantics follow Lua, not JS: `0` and `""` are truthy in Lua, falsy in JS
- Lua's table indexing (1-based, no `length` for holes) replaces JS arrays: pass-through types abstract this but iteration order changes
- Importing JS-only libraries silently fails at translation, only `@types` packages with Lua-runtime equivalents work
- `tstlc` is the CLI; build configs are different from `tsc`: sharing a `tsconfig.json` with web projects requires careful `compilerOptions` split

## Progressive disclosure

- Read [references/namespaces-vs-classes.md](references/namespaces-vs-classes.md) - Load when choosing code organization, namespaces, or enums for clean Lua output
- Read [references/multi-return-functions.md](references/multi-return-functions.md) - Load when implementing Lua-style multiple return values
- Read [references/coroutine-patterns.md](references/coroutine-patterns.md) - Load when implementing cooperative multitasking
- Read [references/lua-interop.md](references/lua-interop.md) - Load when calling Lua code from TypeScript
- Read [references/tstl-decorators.md](references/tstl-decorators.md) - Load when using TSTL-specific decorators
- Read [references/performance-tips.md](references/performance-tips.md) - Load when optimizing for Lua GC/JIT or generated code is slow or bloated
- Read [references/type-safety.md](references/type-safety.md) - Load when maintaining types across TS/Lua boundary
- Read [references/avoiding-heavy-features.md](references/avoiding-heavy-features.md) - Load when transpiled output is unexpectedly large
- Read [references/tsconfig.md](references/tsconfig.md) - Load when configuring TSTL compiler options
Files in this package (14)
  • SKILL.md 3 KB
  • SOURCES.md 1 KB
  • eval-queries.json 5 KB
  • evals.json 2 KB
  • moon.yml 1 KB
  • references/avoiding-heavy-features.md 1 KB
  • references/coroutine-patterns.md 1 KB
  • references/lua-interop.md 1 KB
  • references/multi-return-functions.md 1 KB
  • references/namespaces-vs-classes.md 1 KB
  • references/performance-tips.md 1 KB
  • references/tsconfig.md 1 KB
  • references/tstl-decorators.md 1 KB
  • references/type-safety.md 1 KB

Versions

The database has no other skills named typescript-to-lua-guide.

Database snapshot: 13.11.2026 · package version a2a6b06c28bd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86lua
    Lua开发专家助手。当用户需要进行Lua脚本开发、游戏脚本、嵌入式脚本、Nginx/Redis脚本或Neovim配置时调用。
  • 90lua-guide
    Use when editing general-purpose Lua 5.4+: modules, scripts, configuration. Triggers on `.lua` files and prompts about module patterns, local scoping, metatables, coroutines, error handling, even when the user doesn't say 'Lua'.
  • 100defold-core
    Build and debug the core of a Defold game in Lua: game.project settings, collections, game objects and components, script lifecycle and self state, go.property, input focus and bindings, URLs and message passing, factories, collection factories and collection proxies, plus…
  • 100lua-embedding-scripting
    Use this skill when embedding Lua runtimes into C, Go, or Rust applications for dynamic plugin scripting and configuration rules.
  • 90lua-development
    Lua language and module development standards for Cybercore and Omarchy-related work. Use for general Lua coding, modules, performance, error handling, testing, and embedded/scripting tasks outside pure Hyprland config.
  • 90lua-opinionated-guide
    Use when tuning performance-critical Lua hot paths: the tunings especially benefit LuaJIT, and the principles apply to vanilla Lua 5.4 too. A focused overlay that covers only hot-path performance, not Lua fundamentals. Triggers on `.lua` files in performance-sensitive or LuaJIT…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.