Runtime Context

ctx 是 Tissue Preview Runtime 在脚本生命周期函数中传入的上下文对象。

它是脚本访问当前 GameObject、项目数据、共享状态和运行时能力的入口。

export default {
  start(ctx) {
    ctx.transform.setPosition(100, 200)
  },
  update(ctx, dt) {
    // dt 的单位是秒
  }
}

ctx 不是 Phaser

ctx 不是 Phaser 的原始对象，也不是 Phaser Scene。

不要根据 Phaser、Cocos、Godot 或其他引擎经验猜测 API。只有 Runtime Manifest 中列出的 API 才是支持的。

不支持：

ctx.now()
ctx.time
ctx.clock
ctx.scene.time
ctx.gameObject.list
ctx.parentContainer
ctx.physics

如果需要这些能力，应使用 Tissue 提供的封装 API，或在缺少能力时报告工具问题。

生命周期

脚本资源推荐导出一个对象：

export default {
  awake(ctx) {},
  start(ctx) {},
  update(ctx, dt) {},
  onPointerDown(ctx) {},
  onDestroy(ctx) {}
}

awake(ctx)

脚本创建时调用。适合初始化字段。

awake(ctx) {
  this.vy = 0
  this.elapsed = 0
}

start(ctx)

脚本启动时调用一次。适合注册输入事件、初始化共享状态。

start(ctx) {
  ctx.state.score = 0
  ctx.input.onKeyDown('SPACE', () => {
    this.vy = -320
  })
}

update(ctx, dt)

每帧调用。

dt 的单位是秒，不要再除以 1000。

update(ctx, dt) {
  this.elapsed += dt
  ctx.transform.setPosition(ctx.self.x, ctx.self.y + 100 * dt)
}

onPointerDown(ctx)

当前对象被点击时调用。

onPointerDown(ctx) {
  ctx.state.started = true
  ctx.node.hide()
}

onDestroy(ctx)

预览关闭或对象销毁时调用。

重要规则

只使用 manifest 中的 API

如果文档或 manifest 没列出某个 API，不要使用。

错误：

const t = ctx.now()

正确：

this.elapsed += dt

dt 已经是秒

错误：

this.y += speed * (dt / 1000)

正确：

this.y += speed * dt

用 ctx.state 做跨脚本共享状态

多个脚本之间共享状态时使用 ctx.state。

// StartButton.js
onPointerDown(ctx) {
  ctx.state.started = true
  ctx.node.hide()
}

// Bird.js
update(ctx, dt) {
  if (!ctx.state.started) return
  // running gameplay
}

用 this 保存当前脚本实例状态

单个脚本自己的计时器、速度、临时状态应放在 this 上。

awake(ctx) {
  this.elapsed = 0
}

update(ctx, dt) {
  this.elapsed += dt
}

常用 ctx 属性

ctx.self

当前编辑器 GameObject 数据。

常用于读取对象初始位置、尺寸、名称等。

const startX = ctx.self.x
const width = ctx.self.width

注意：如果对象位置已被 runtime 修改，优先使用 ctx.transform 来设置，不要手动改 ctx.self.x。

ctx.gameObject

当前对象对应的 Phaser GameObject。

一般不建议直接操作 Phaser 内部结构。优先使用 Tissue Runtime API。

可以读取简单属性，但不要假设它是 Container：

// 不推荐
ctx.gameObject.list
ctx.gameObject.parentContainer

Prefab 在 Tissue 中是 GameObject 层级，不是 Phaser Container。

ctx.project

当前项目数据。

常用于读取画布大小：

const width = ctx.project.width
const height = ctx.project.height

ctx.state

当前预览场景的共享状态对象。

适合保存：

• started
• score
• gameOver
• activePipes
• player reference

示例：

start(ctx) {
  if (typeof ctx.state.score !== 'number') {
    ctx.state.score = 0
  }
}

常见替代方案

不支持写法	替代方案
ctx.now()	this.elapsed += dt
ctx.time	update(ctx, dt) 中累加时间
ctx.scene.time	后续如需要由 Tissue 提供 ctx.time 封装
ctx.gameObject.list	ctx.instantiatePrefab() 返回的 instance.objects / instance.find(name)
ctx.parentContainer	使用 Tissue GameObject 层级或 Prefab instance handle
ctx.physics	使用 ctx.transform + ctx.collider，后续如需要再设计 Physics 组件

AI 使用规则

AI 生成脚本时必须遵守：

• ctx 是 Tissue Runtime Context，不是 Phaser。
• 不要猜 API。
• 只使用 Runtime Manifest 中列出的 API。
• dt 是秒。
• 计时用 this.elapsed += dt。
• 跨脚本共享状态用 ctx.state。
• Prefab 实例控制用 ctx.instantiatePrefab() 返回的 handle。
• 如果缺少能力，报告工具问题，不要写静默 fallback。

Manifest

机器可读 manifest：

• runtime_manifest.json