roblox-typescript-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roblox TypeScript Developer

Roblox TypeScript 开发者

Workflow for Roblox projects authored in TypeScript and compiled to Luau with roblox-ts. The build pipeline, package ecosystem, and interop surface differ from plain Luau, so keep them distinct from Luau-authoring habits.

适用于使用 TypeScript 编写并通过 roblox-ts 编译为 Luau 的 Roblox 项目工作流。其构建流水线、包生态系统和互操作层面与纯 Luau 开发不同，因此需与 Luau 开发习惯区分开。

Build pipeline

构建流程

The canonical flow is

.ts

source →

rbxtsc

(the roblox-ts compiler) →

.lua

under

out/

→

rojo serve

rojo build

→ Studio.

Compiler:
```
roblox-ts
```
(npm), binary
```
rbxtsc
```
.
Types:
```
@rbxts/types
```
, auto-published against the Roblox API.
Config:
```
tsconfig.json
```
with
```
compilerOptions
```
targeting roblox-ts.
Rojo maps the compiled
```
out/
```
directory into the place file, so
```
default.project.json
```
points at compiled output, not the
```
.ts
```
source.

Edit

.ts

source as the source of truth; do not patch generated Luau under

out/

unless the user asks for an emergency generated-output patch.

标准流程为：

.ts

源文件 →

rbxtsc

（roblox-ts 编译器）→

out/

目录下的

.lua

文件 →

rojo serve

rojo build

→ Studio。

编译器：
```
roblox-ts
```
（npm 包），二进制文件
```
rbxtsc
```
。
类型定义：
```
@rbxts/types
```
，针对 Roblox API 自动发布。
配置：带有
```
compilerOptions
```
且目标为 roblox-ts 的
```
tsconfig.json
```
。
Rojo 将编译后的
```
out/
```
目录映射到场景文件中，因此
```
default.project.json
```
指向编译输出，而非
```
.ts
```
源文件。

以

.ts

源文件为唯一可信源；除非用户要求紧急修补生成的输出文件，否则不要修改

out/

目录下生成的 Luau 代码。

Project detection

项目检测

Recognize a roblox-ts project by

rbxtsc

package.json

scripts, a

tsconfig.json

with roblox-ts settings,

@rbxts/*

packages, and an

out/

directory mapped by

default.project.json

可通过以下特征识别 roblox-ts 项目：

package.json

脚本中包含

rbxtsc

、带有 roblox-ts 设置的

tsconfig.json

、

@rbxts/*

包，以及由

default.project.json

映射的

out/

目录。

TypeScript-to-Luau interop

TypeScript 与 Luau 互操作

Luau and TypeScript index and call differently; see

references/typescript-luau-interop.md

for the full idiom set. The main ones:

Roblox Instances are 1-indexed; prefer the
```
@rbxts/types
```
API surface over raw numeric indexing.
Multiple return values use
```
LuaTuple<[A, B]>
```
rather than an array.
Preserve Luau colon-call method semantics when the generated code depends on
```
self
```
/
```
this
```
.
Imports map to Rojo Instance paths through the compiled
```
out/
```
tree, not to the
```
.ts
```
filesystem path.

Luau 和 TypeScript 的索引与调用方式不同；完整规范请参考

references/typescript-luau-interop.md

。主要规范如下：

Roblox 实例采用 1 索引；优先使用
```
@rbxts/types
```
API 而非原始数字索引。
多返回值使用
```
LuaTuple<[A, B]>
```
而非数组。
当生成代码依赖
```
self
```
/
```
this
```
时，保留 Luau 的冒号调用方法语义。
导入通过编译后的
```
out/
```
目录映射到 Rojo 实例路径，而非
```
.ts
```
文件系统路径。

Server/client boundary

服务器/客户端边界

The Roblox authority model is unchanged by TypeScript: authoritative state and validation live on the server; the client handles input, display, prediction, and requests; Remote parameters are type- and permission-checked; DataStore writes are throttled, retried, and failure-handled.

Roblox 的权限模型不会因 TypeScript 而改变：权威状态与验证逻辑位于服务器端；客户端处理输入、显示、预测与请求；Remote 参数需进行类型与权限检查；DataStore 写入需进行限流、重试与错误处理。

Verify

验证

Prefer the project's own scripts:

npm run build

npx rbxtsc

rojo sourcemap

selene

stylua

If only static analysis is possible, say explicitly that no Studio / Play Solo run happened.

优先使用项目自身的脚本：
```
npm run build
```
、
```
npx rbxtsc
```
、
```
rojo sourcemap
```
、
```
selene
```
、
```
stylua
```
。
若仅能进行静态分析，请明确说明未进行 Studio / 单人游戏运行测试。

Output

输出

Changes: which
```
.ts
```
files and behavior changed, and what Luau was generated.
Server/client boundary: where authoritative logic lives.
Remote/DataStore risk: interfaces added or changed.
Verification: checks actually run; note when Studio cannot run.

变更内容：哪些
```
.ts
```
文件和行为发生了变更，以及生成了哪些 Luau 代码。
服务器/客户端边界：权威逻辑所在位置。
Remote/DataStore 风险：新增或变更的接口。
验证情况：实际执行的检查；注明无法运行 Studio 测试的情况。