ZorixScript 完整说明 | Human + AI Guide

1. 快速开始

体验入口：https://engine.zorix.it

ZorixScript 写在 Zorix Engine 右侧 Inspector 的 Script Source 里。选择一个物体，把 Behaviour 设置为 zorixscript，写入脚本，然后点击 Play。

start:
  log hello zorix
  color #44aaff

update:
  spin y 1.2

2. 人类使用说明

1. 选择物体在左侧 Hierarchy 点选 Player、Zorix Tree、Enemy 等对象。

2. 找到脚本框右侧 Inspector → ZorixScript → Script Source。

3. 写脚本使用 start: 和 update: 编写行为。

4. 运行点击顶部 Play，脚本才会运行。

脚本结构

结构	含义	适合放什么
`start:`	运行时只执行一次	初始化颜色、变量、重力、速度
`update:`	每帧执行	移动、旋转、按键、相机跟随、动画
`// comment`	注释	给自己或 AI 解释代码

最常见目标

想做什么	脚本
树左右移动	`update: sway x 1.3 0.8`
物体旋转	`update: spin y 1.2`
隐藏树	`start: hide Zorix Tree`
按 E 隐藏树	`update: ifkey e hide Zorix Tree`
玩家 WASD 移动	`update: ifkey w move 0 0 -4 ifkey s move 0 0 4`

3. ZorixScript 命令表

变量与条件

命令	说明	例子
`var name value`	创建变量	`var hp 100`
`set name value`	设置变量	`set speed 4`
`add name value`	按秒累加变量	`add timer 1`
`ifvar name > value command`	变量条件	`ifvar timer > 3 hide Zorix Tree`
`ifkey key command`	按键条件	`ifkey e toggle Zorix Tree`

Transform / 动画

命令	说明	例子
`move x y z`	按秒移动	`move 0 0 4`
`position x y z`	设置绝对位置	`position 0 1 0`
`rotate x y z`	设置旋转	`rotate 0 1.57 0`
`rotateBy x y z`	持续旋转	`rotateBy 0 1 0`
`scale value`	统一缩放	`scale 1.5`
`scale3 x y z`	三轴缩放	`scale3 1 2 1`
`spin axis speed`	绕轴旋转	`spin y 1.2`
`sway axis speed distance`	左右/上下/前后来回移动	`sway x 1.3 0.8`
`bob speed distance`	上下浮动	`bob 0.8 1`
`orbit speed radius`	绕中心移动	`orbit 0.7 3`
`pulse amount`	呼吸缩放	`pulse 0.15`

材质、物理、对象控制

命令	说明	例子
`color #hex`	改颜色	`color #44aaff`
`opacity value`	透明度	`opacity 0.5`
`roughness value`	粗糙度	`roughness 0.2`
`metallic value`	金属度	`metallic 1`
`gravity on/off`	开启重力	`gravity on`
`velocity x y z`	设置速度	`velocity 0 5 0`
`bounce value`	弹性	`bounce 0.8`
`hide name`	隐藏对象	`hide Zorix Tree`
`show name`	显示对象	`show Zorix Tree`
`toggle name`	切换显示隐藏	`toggle Zorix Tree`
`enable/disable name`	启用/禁用对象脚本	`disable Enemy`

生成、特效、相机

命令	说明	例子
`spawn type x y z`	生成物体	`spawn coin 1 0 0`
`emit`	生成粒子	`emit`
`camera follow x y z`	相机跟随偏移	`camera follow 4 3 6`
`camera look`	相机看向物体	`camera look`
`lookAtCamera`	物体看向相机	`lookAtCamera`
`log message`	输出日志	`log started`

4. 完整脚本例子

树左右移动

update:
  sway x 1.3 0.8
  spin z 0.12

玩家控制

start:
  gravity on
  bounce 0.1

update:
  ifkey w move 0 0 -4
  ifkey s move 0 0 4
  ifkey a move -4 0 0
  ifkey d move 4 0 0
  ifkey space velocity 0 5 0
  camera follow 4 3 6
  camera look

计时后隐藏树

start:
  var timer 0

update:
  add timer 1
  ifvar timer > 2 hide Zorix Tree

按键生成金币

update:
  ifkey c spawn coin 0 1 0

2D 平台角色

start:
  gravity on
  bounce 0.05

update:
  ifkey a move -4 0 0
  ifkey d move 4 0 0
  ifkey space velocity 0 6 0
  camera follow 0 8 0.01
  camera look

5. UI Designer 和按钮动作

底部切到 UI Designer。
点 Add Button。
点击场景上的按钮，右侧 Inspector 会变成 UI Inspector。
设置 Action 和 Target Object。
点 Play，然后点击按钮执行动作。

Action	作用	例子
`hide`	隐藏目标	Target: `Zorix Tree`
`show`	显示目标	Target: `Zorix Tree`
`toggle`	切换显示/隐藏	Target: `Zorix Tree`
`spawn`	生成物体	Spawn Type: `coin`
`runScript`	运行一行 ZorixScript	Script: `hide Zorix Tree`

按钮隐藏树：Action 选 hide，Target Object 写 Zorix Tree。运行后点击按钮，树会消失。

6. 给 AI 看的 Markdown 规格

把下面这段复制给 AI，它就知道如何帮你写 ZorixScript。

# ZorixScript Specification For AI

Experience URL: https://engine.zorix.it

ZorixScript is the scripting language inside Zorix Engine. It is written in the Inspector panel under Behaviour = `zorixscript` and Script Source. The user selects an object, writes the script, then presses Play.

## Syntax

- One command per line.
- Empty lines are ignored.
- Lines starting with `//` are comments.
- `start:` runs once when runtime begins.
- `update:` runs every frame.
- Commands outside blocks run every frame, but prefer `update:`.

## Variables

```zorixscript
start:
  var timer 0
  var speed 2

update:
  add timer 1
  set speed 4
  ifvar timer > 3 color #ff3355
```

Supported condition operators: `>`, `<`, `==`, `!=`.

## Keyboard

```zorixscript
update:
  ifkey w move 0 0 -4
  ifkey s move 0 0 4
  ifkey a move -4 0 0
  ifkey d move 4 0 0
  ifkey space velocity 0 5 0
```

On mobile, prefer UI Designer buttons instead of keyboard commands.

## Movement Commands

- `move x y z`
- `position x y z`
- `rotate x y z`
- `rotateBy x y z`
- `scale value`
- `scale3 x y z`
- `spin axis speed`
- `sway axis speed distance`
- `bob speed distance`
- `orbit speed radius`
- `pulse amount`

Example tree sway:

```zorixscript
update:
  sway x 1.3 0.8
  spin z 0.12
```

## Material Commands

- `color #hex`
- `opacity value`
- `roughness value`
- `metallic value`

## Physics Commands

- `gravity on`
- `gravity off`
- `velocity x y z`
- `bounce value`

## Scene Object Control

- `hide object name`
- `show object name`
- `toggle object name`
- `enable object name`
- `disable object name`

Example:

```zorixscript
start:
  hide Zorix Tree
```

## Spawn / FX / Camera

- `spawn type x y z`
- `emit`
- `camera follow x y z`
- `camera look`
- `lookAtCamera`
- `log message`

Spawn types include: cube, sphere, capsule, cylinder, cone, torus, tree, vehicle, house, tower, bridge, coin, enemy, platform, portal, terrain, water, particles, pointLight, spotLight.

## UI Designer Button Actions

UI buttons can have:

- `hide`
- `show`
- `toggle`
- `spawn`
- `runScript`

To make a button hide the tree:

- Action: `hide`
- Target Object: `Zorix Tree`

## Common Complete Examples

Player controller:

```zorixscript
start:
  gravity on
  bounce 0.1

update:
  ifkey w move 0 0 -4
  ifkey s move 0 0 4
  ifkey a move -4 0 0
  ifkey d move 4 0 0
  ifkey space velocity 0 5 0
  camera follow 4 3 6
  camera look
```

Hide tree after 2 seconds:

```zorixscript
start:
  var timer 0

update:
  add timer 1
  ifvar timer > 2 hide Zorix Tree
```

2D platform controller:

```zorixscript
start:
  gravity on
  bounce 0.05

update:
  ifkey a move -4 0 0
  ifkey d move 4 0 0
  ifkey space velocity 0 6 0
  camera follow 0 8 0.01
  camera look
```