docs: explain scene graphics and composite example execution

This commit is contained in:
2026-11-12 19:51:41 +08:00
parent 99ce4e3fc6
commit 7f7464ae2b
8 changed files with 135 additions and 0 deletions
+24
View File
@@ -5,6 +5,7 @@
class CampusPanel: Column {
// 按当前出现位置 geometry 创建一条背景命令,子项由展示遍历继续绘制。
function paint(self: CampusPanel, mount: Mount, geometry: Bounds): DisplayList {
// source_paint 为每个卡片出现调用;fill 是本轮新结果,允许写字段,不能在这里修改课程或作业模型。
fill = PaintCommand()
fill.kind = "roundedRect"
fill.x = geometry.x
@@ -18,9 +19,11 @@ class CampusPanel: Column {
}
// 通过额外 width 字段固定表格列的期望宽,保持成绩表头和行对齐。
class CampusCell: Column {
// 这是源子类的期望宽度策略,不是某个 Mount 的最终宽度;相同列宽仍要服从父 Constraints。
width: Number
// 先算子内容自然高度,再改新测量结果宽度,保留真实字体引起的高度。
function measure(self: CampusCell, mount: Mount, constraints: Constraints): MeasureResult {
// source_layout 先调用覆盖,再显式委托 Column 得到新 MeasureResult;只改返回结果,不写 content 的业务状态。
result = Column.measure(self, mount, constraints)
result.width = self.width
return result
@@ -30,10 +33,12 @@ class CampusCell: Column {
class CampusSidebar: Column {
// 返回固定168x620期望尺寸,外层 ScrollBlock 承担超出区域的滚动。
function measure(self: CampusSidebar, mount: Mount, constraints: Constraints): MeasureResult {
// 每个侧栏出现的只读测量入口;固定返回值仍受父约束处理,不是强制原生窗口至少 620 高。
return MeasureResult(168, 620)
}
// 为导航区创建深红背景,位置/大小来自当前Mount,文字等子项保持独立命令。
function paint(self: CampusSidebar, mount: Mount, geometry: Bounds): DisplayList {
// 侧栏背景命令只覆盖当前容器,子按钮和文字通过独立出现继续绘制,避免在父命令里重复画子树。
fill = PaintCommand()
fill.kind = "roundedRect"
fill.x = geometry.x
@@ -50,10 +55,12 @@ class CampusNav: Button {
background: String
// 导航按钮期望144x40,确保四个入口宽高一致。
function measure(self: CampusNav, mount: Mount, constraints: Constraints): MeasureResult {
// source_layout 调用此固定尺寸策略,实际测量结果仍由宿主验证,再交给父导航容器安排。
return MeasureResult(144, 40)
}
// 取原生按钮背景命令改色/圆角;文字由后面 replace 后的子项绘制,不在此重复生成。
function paint(self: CampusNav, mount: Mount, geometry: Bounds): DisplayList {
// 原生按钮生成本轮临时命令,at(0) 只取背景;下面 campusNav 替换的白字孩子由统一遍历画出。
fill = Button.paint(self, mount, geometry).commands.at(0)
fill.color = self.background
fill.radius = 7
@@ -62,6 +69,7 @@ class CampusNav: Button {
}
// 课程业务记录,grade/progress 被多个页面绑定读取,其余静态字段构建时直接读取。
class CampusCourse {
// grade/progress 用 ui.textOf 注册实时依赖;其余字段传给 TextBlock 时只读取构造当时的值。
title: String
code: String
teacher: String
@@ -79,6 +87,7 @@ class CampusWork {
course: CampusCourse
// 模拟提交只改状态、文件名提示、待办和结果文字,不访问磁盘或网络。
function submit(self: CampusWork, event: Event): Unit {
// campusSubmitButton 的 click 连接调用;没有文件选择或成绩计算,重复点击会再次写相同预设状态。
self.status = "已提交 · 等待评分"
self.submission = "lab01.endor · 已提交示例内容"
self.todo = "已完成本次实验提交"
@@ -86,6 +95,7 @@ class CampusWork {
}
// 应用预设92分和反馈,并更新所属课程成绩/进度;绑定让仪表盘、课程、成绩页同步观察。
function assess(self: CampusWork, event: Event): Unit {
// campusAssessButton 派发到这里,course 引用 campusProgramming;只改该课程,数学与英语保持原值。
self.status = "已评分"
self.score = "92 / 100"
self.feedback = "结构清晰,边界情况处理完整。建议补充函数说明。"
@@ -97,6 +107,7 @@ class CampusWork {
}
// 恢复初始实验与课程状态,保留所有原对象和绑定,便于反复演示。
function reset(self: CampusWork, event: Event): Unit {
// campusResetButton 的事件入口恢复共享模型字段,不重新创建七页,不需要逐页重新注册文字绑定。
self.status = "未提交"
self.score = "— / 100"
self.feedback = "提交后可在此查看教师反馈。"
@@ -109,6 +120,7 @@ class CampusWork {
}
// 用统一包装构造表格单元格;传入的content是已有Block引用。
function campusCell(content: Block, width: Number): Block {
// campusGradeRow 和成绩表头调用;width 放在原生 Column 的单个孩子之后,属于源字段而非额外孩子。
return CampusCell(0, 0, content, width)
}
// 显式事件适配器把click的Event与Page.open可选Window参数分开,不能直接把Event误当窗口。
@@ -116,17 +128,21 @@ class CampusTarget {
page: Page
// 事件参数在适配器这一层消化,Page.open 只接收其声明的可选 Window。
// 消费事件但不传给Page.open;无参open表示在合适窗口打开/激活目标页。
// campusLink/campusNav 保存此绑定方法;点击时以已保存的真实 Page 为目标,不按标题字符串重新找页。
function open(self: CampusTarget, event: Event): Unit { self.page.open() }
}
// 为普通按钮创建持有目标Page的适配器,并把其绑定方法注册为click回调。
function campusLink(label: String, target: Page): Button {
// 由卡片、课程正文和作业详情等组合函数调用,每次生成独立按钮/适配器,但复用传入 target 页身份。
button = Button(label)
action = CampusTarget(target)
// 连接持有绑定接收者所需引用,action 局部变量离开函数不代表回调丢失目标;调用方不需额外保存适配器。
button.on("click", action.open)
return button
}
// 构造带指定背景的导航按钮,替换原生文字子槽为白字,然后复用事件适配器连接目标页。
function campusNav(label: String, target: Page, background: String): Button {
// campusNavigation 调用,先用源字段构造导航按钮,再替换稳定槽 0 的文字,不把背景字符串误传成孩子。
button = CampusNav(label, background)
button.replace(0, TextBlock(label, 1, "#FFFFFF"))
action = CampusTarget(target)
@@ -135,6 +151,7 @@ function campusNav(label: String, target: Page, background: String): Button {
}
// 用目标Page和四个色调参数构建整块导航;不同页面复用目标资源但用不同高亮背景。
function campusNavigation(home: Page, course: Page, assignments: Page, grades: Page, homeTone: String, courseTone: String, workTone: String, gradeTone: String): Block {
// 顶层调用四次建立不同高亮版本;四个 Page 参数只提供导航目标,此函数不直接 open 或 render 它们。
return CampusSidebar(12, 10,
TextBlock("Endor", 2, "#FFFFFF"),
TextBlock("Campus", 1, "#E7BAC0"), Spacer(16),
@@ -148,6 +165,7 @@ function campusNavigation(home: Page, course: Page, assignments: Page, grades: P
}
// 把演示导航与标题/正文横排,外层有限ScrollBlock启用双轴,容纳固定宽度演示内容。
function campusShell(navigation: Block, title: String, subtitle: String, body: Block): Block {
// 七个 render 的参数求值调用本函数,各自新建外层滚动对象;传入 navigation 可共享,偏移则按出现分别保存。
scroll = ScrollBlock(1120, 680,
Row(24, 28, navigation,
Column(0, 16,
@@ -159,6 +177,7 @@ function campusShell(navigation: Block, title: String, subtitle: String, body: B
}
// 卡片静态显示课程代码/标题/教师,grade 用绑定随评分变化,入口按钮引用真实课程Page。
function campusCourseCard(course: CampusCourse, page: Page, color: String): Block {
// 仪表盘为三门课各调用一次;color 同时用于静态色条与成绩文字,grade 的实时值仍来自传入 course。
return CampusPanel(0, 0,
RectBlock(248, 44, 8, color),
Column(16, 8,
@@ -170,6 +189,7 @@ function campusCourseCard(course: CampusCourse, page: Page, color: String): Bloc
}
// 成绩表一行复用固定列宽单元格,当前grade为响应式文字,详情链接指向指定课程页。
function campusGradeRow(course: CampusCourse, target: Page): Block {
// 成绩总览逐门课程调用,创建新的表格视觉行,不复制 CampusCourse;详情按钮保留对应课程 Page。
return Column(0, 12,
Row(0, 0,
campusCell(TextBlock(course.title), 240),
@@ -180,6 +200,7 @@ function campusGradeRow(course: CampusCourse, target: Page): Block {
}
// 组合课程概况/进度和静态学习单元;上方两个链接复用作业/成绩Page,不创建新页面。
function campusCourseBody(course: CampusCourse, intro: String, moduleOne: String, moduleTwo: String, moduleThree: String, assignments: Page, grades: Page): Block {
// 三个课程页调用同一构造函数,各自传不同课程模型/静态单元文案;只有明确 textOf 的字段会随模型改动重算。
return Column(0, 20,
Row(0, 16, campusLink("作业与提交", assignments), campusLink("查看成绩", grades)),
CampusPanel(20, 12,
@@ -202,6 +223,7 @@ campusProgramming = CampusCourse("计算机程序设计", "CS 101", "陈老师
campusMathematics = CampusCourse("高等数学 I", "MATH 101", "周老师 · 周一 / 周三", "91.0%", "已完成 4 / 6 个学习单元")
campusEnglish = CampusCourse("学术英语", "ENG 102", "许老师 · 周五", "89.0%", "已完成 3 / 5 个学习单元")
campusWork = CampusWork("未提交", "— / 100", "提交后可在此查看教师反馈。", "尚无提交内容", "1 项实验待提交", "这是一个本地提交与评分演示。", campusProgramming)
// course 只关联程序设计模型;课程标题/成绩等对象引用与页面资源随后通过各组合函数串成同一托管对象图。
// 先创建全部七个Page,允许导航按钮互相引用;随后逐一render建立内容。
campusDashboard = Page()
campusDashboard.title = "Campus · 仪表盘"
@@ -281,6 +303,7 @@ campusAssessButton = Button("应用示例评分")
campusAssessButton.on("click", campusWork.assess)
campusResetButton = Button("恢复演示数据")
campusResetButton.on("click", campusWork.reset)
// 注册三个方法只建立监听,不立即执行预设提交/评分/恢复;首次所有绑定读取上面的模型初值。
// 详情页组合要求、提交状态、操作按钮和反馈;所有输入仍只是预设本地状态转换。
campusWorkPage.render(campusShell(campusAssignmentNav, "实验 01:对象与函数", "CS 101 / 作业 / 提交详情",
Column(0, 20,
@@ -301,3 +324,4 @@ campusWorkPage.render(campusShell(campusAssignmentNav, "实验 01:对象与函
ui.textOf(campusWork, "result", 1, "#7C8793"))))
// 逐页render会改变当前活动页,最后显式选择仪表盘作为打开后的首页。
campusDashboard.activate()
// 激活只请求展示已有仪表盘,保留其余六页及共享课程/实验对象;所有页面都没有独立数据库或独立 VM。
+68
View File
@@ -1,24 +1,32 @@
// All application state, motion, fire, hit reactions and scheduling live here.
// Tessera only supplies generic graphics/text/geometry, input and owned Tasks.
// 整个文件作为一次源码输入加载:应用状态、跟随运动、火焰与定时重绘均由源方法实现,宿主提供通用图形与任务能力。
// graphics 是通用图形入口,math 提供数学/时钟函数;assets 为相对于运行工作目录的素材路径,不是网络地址。
g = ui.graphics
math = g.math
assets = "examples/assets/manuscript/"
font = g.loadFont(assets + "IMFellEnglish-Regular.ttf", "IM FELL English")
// 读取故事后截取大范围正文,再预先整形为两套字号/行距;paint 根据可用宽度选择,不在每帧重新读文件加载字体。
story = g.textSlice(g.readText(assets + "story.txt"), 1, 1000000)
bodyText = g.prepareText(story, font, 21, 34, "#2A1A0A", 2)
smallText = g.prepareText(story, font, 16, 26, "#2A1A0A", 2)
hint = g.prepareText("Move the pointer. Hold to breathe fire.", font, 14, 22, "#705B44", 2)
// artwork 调用的精灵包装:image 是共享图片资源,返回新的绘制命令;位置/锚点/旋转不写回图片对象。
function sprite(image: Object, x: Number, y: Number, scale: Number, angle: Number, ax: Number, ay: Number): Object {
return g.sprite(image, x, y, image.width * scale, image.height * scale, angle, ax, ay, 1)
}
function wrappedAngle(angle: Number): Number {
// step 的姿态插值调用,把差值归一化到 [-π,π],跨越一圈边界时仍选择短方向;循环不修改传入业务姿态。
result = angle
// 大于正半圈就逐圈减去 2π,允许输入差值超过一圈,不只处理一次越界。
while result > math.pi { result = result - math.pi * 2 }
// 小于负半圈则反向逐圈加回,与上面共同覆盖任意有限角度差。
while result < -math.pi { result = result + math.pi * 2 }
return result
}
class Segment {
// 龙身体的单节状态,位置为手稿设计坐标,angle 为弧度;step 修改姿态,artwork 只读它生成本轮命令。
x: Number
y: Number
angle: Number
@@ -27,11 +35,14 @@ class Segment {
// Asset orientation is application data: angles are radians, clockwise in
// screen coordinates. Each PNG is calibrated against its own long axis.
class FireArt {
// image 为火焰图片资源,axis 为该图片长轴方向校准,artwork 用速度方向减它以正确旋转素材。
image: Object
axis: Number
}
// 顶层 fireDirections 的轻量记录,loadFire 逐一取 angle,与 Layer 2..11 的图片顺序对应。
class Direction { angle: Number }
class Flame {
// x/y、vx/vy 为设计坐标中的粒子位置与每步速度;age 按 step 次数递增,size/art 控制绘制,不使用独立后台线程。
x: Number
y: Number
vx: Number
@@ -41,6 +52,7 @@ class Flame {
art: FireArt
}
class Dragon {
// 三个列表分别保存龙节、活跃粒子与校准素材;图片字段共享资源,目标/按压/时间/seed 则为可变应用状态。
segments: Object
flames: Object
fireImages: Object
@@ -54,11 +66,13 @@ class Dragon {
lastMove: Number
seed: Number
function random(self: Dragon): Number {
// step 产生火焰时调用的确定性伪随机序列;先推进 seed,再取正弦混合值的小数部分,返回 [0,1)。
self.seed = self.seed + 1
value = math.sin(self.seed * 12.9898) * 43758.5453
return value - math.floor(value)
}
function pointer(self: Dragon, event: Event): Unit {
// pointermove 和 down 调用;event 为当前出现局部指针坐标,bounds 给出可用宽度,反变换与 paint 的缩放/留白保持一致。
bounds = event.mount.bounds()
scale = math.max(0.2, math.min(1, (bounds.width - 40) / 700))
self.targetX = (event.x - (bounds.width - 700 * scale) / 2) / scale
@@ -66,38 +80,49 @@ class Dragon {
self.lastMove = math.now()
}
function down(self: Dragon, event: Event): Unit {
// pointerdown 先更新目标和最近移动时刻,再开启喷火;这里只改状态,粒子生成留到定时 step。
self.pointer(event)
self.pressed = 1
}
// pointerup 关闭新粒子生成,已有火焰仍按后续 step 继续移动并到龄移除。
function up(self: Dragon, event: Event): Unit { self.pressed = 0 }
function leave(self: Dragon, event: Event): Unit {
// pointerleave/pointercancel 共用入口,清按压并把最近移动时间置为过期值,使龙回到待机姿态。
self.pressed = 0
self.lastMove = -10
}
function step(self: Dragon): Unit {
// Manuscript.tick 每次定时恢复调用一次;这是可写业务阶段,更新姿态/粒子供下一轮只读 paint 使用。
self.time = math.now()
// 超过两秒没有指针移动时,用平滑插值回到预设弧形,不继续追踪旧目标。
if self.time - self.lastMove > 2 {
// x/y 为本轮待机目标游标,i 从头节开始;float 明确提供可进行浮点运算的起始值。
x = math.float(150)
y = math.float(110)
i = 0
while i < self.segments.count {
// 顺序访问每一节,以索引定义弧度;每轮只修改这一节的姿态,再推进游标。
s = self.segments.at(i)
angle = -i / 19 * math.pi * 0.7
if i > 0 {
// 头部使用固定起点,后续节沿目标角度后退 30 设计单位,形成待机弧线。
x = x - math.cos(angle) * 30
y = y - math.sin(angle) * 30
}
s.x = s.x + (x - s.x) * 0.12
// 位置与角度都只靠近目标的 12%,wrappedAngle 防止跨 ±π 时绕远路。
s.y = s.y + (y - s.y) * 0.12
s.angle = s.angle + wrappedAngle(angle - s.angle) * 0.12
i = i + 1
}
} else {
// 最近有输入时,头部追逐指针目标,其余节依次根据已经更新的前一节重建位置。
head = self.segments.at(0)
dx = self.targetX - head.x
dy = self.targetY - head.y
distance = math.sqrt(dx * dx + dy * dy)
if distance > 4 {
// 距离足够才归一化方向,避免近零除法和微小抖动;速度下限 12,但不会超过剩余距离。
speed = math.min(distance, math.max(12, distance * 0.15))
head.x = head.x + dx / distance * speed
head.y = head.y + dy / distance * speed
@@ -105,6 +130,7 @@ class Dragon {
}
i = 1
while i < self.segments.count {
// 身体从第二节向尾部遍历,限制相对前节弯曲到 ±0.25 弧度,再保持 30 单位节距。
previous = self.segments.at(i - 1)
s = self.segments.at(i)
angle = math.atan2(previous.y - s.y, previous.x - s.x)
@@ -115,6 +141,7 @@ class Dragon {
}
}
i = self.flames.count
// 从列表尾部向前更新粒子,删除当前索引后不会跳过尚未处理的前项。
while i > 0 {
i = i - 1
p = self.flames.at(i)
@@ -122,18 +149,24 @@ class Dragon {
p.x = p.x + p.vx
p.y = p.y + p.vy
p.vx = p.vx * 0.95
// 速度衰减模拟阻力,vy 再减 0.6 令屏幕坐标中的火焰向上飘;年龄是步数,不是秒。
p.vy = p.vy * 0.95 - 0.6
// 存活 12 步后删除,artwork 的透明度使用相同寿命常量,避免留下不可见粒子。
if p.age >= 12 { self.flames.remove(i) }
}
// 按压状态才发射;先更新/清理旧粒子,再检查总数上限。
if self.pressed > 0 {
head = self.segments.at(0)
i = 0
while i < 1 {
// 当前循环上界为 1,即每个 step 至多尝试产生一个粒子;并非一次生成十二个。
if self.flames.count < 12 {
// 仍有容量时随机扰动喷射方向/速度/大小,按素材列表长度选一个合法图片索引。
angle = head.angle + (self.random() - 0.5) * 0.25
speed = 20 + self.random() * 12
size = 12 + self.random() * 8
art = self.fireImages.at(math.floor(self.random() * self.fireImages.count))
// 从头部前方 30 单位发射,位置和速度都在设计坐标里;缩放只在 artwork 转绘制命令时应用。
self.flames.append(Flame(head.x + math.cos(head.angle) * 30, head.y + math.sin(head.angle) * 30, math.cos(angle) * speed, math.sin(angle) * speed, size, 0, art))
}
i = i + 1
@@ -141,29 +174,36 @@ class Dragon {
}
}
function artwork(self: Dragon, ox: Number, oy: Number, scale: Number): Object {
// Manuscript.paint 的只读调用,commands 是本次新列表;允许填写新命令,不能在这里推进 seed 或粒子年龄。
commands = ObjectList()
wing = self.segments.at(5)
commands.append(sprite(self.backWing, ox + wing.x * scale, oy + wing.y * scale, scale * 0.24, wing.angle + math.sin(self.time * 3) * 0.4, 1, 1))
// 后翼先画,再从尾到头画龙节,让头部覆盖后面的身体;索引 5 对应的前翼在该节之后追加形成前景层。
i = self.segments.count
while i > 0 {
// 与 step 的头到尾更新顺序不同,这里反向遍历仅为控制绘制遮盖,不改 segments 顺序。
i = i - 1
s = self.segments.at(i)
ax = math.float(0.5)
if i == 0 {
// 头节使用校准锚点,先追加舌头再追加头图,舌根被头部覆盖。
ax = 0.45
commands.append(sprite(self.tongue, ox + s.x * scale, oy + s.y * scale, scale * 0.24, s.angle, -s.image.width * 0.3 / self.tongue.width, 0.5))
}
commands.append(sprite(s.image, ox + s.x * scale, oy + s.y * scale, scale * 0.24, s.angle, ax, 0.5))
// 前翼只在固定身体节追加,时间正弦控制摆动;图像资源自身仍不发生旋转字段写入。
if i == 5 { commands.append(sprite(self.frontWing, ox + s.x * scale, oy + s.y * scale, scale * 0.24, s.angle - math.sin(self.time * 3 + 0.5) * 0.4, 1, 1)) }
}
i = 0
while i < self.flames.count {
// 每个活跃粒子产生一条新精灵命令;按图片最大边等比缩放,以粒子速度角减素材轴角校准朝向。
p = self.flames.at(i)
image = p.art.image
imageScale = p.size * scale / math.max(image.width, image.height)
angle = math.atan2(p.vy, p.vx) - p.art.axis
drawing = sprite(image, ox + p.x * scale, oy + p.y * scale, imageScale, angle, 0.5, 0.5)
drawing.opacity = 1 - p.age / 12
// 随年龄分别跨过两个色调阈值,第二个 if 可覆盖第一个 tint;二者不是互斥分支。
if p.age > 4 { drawing.tint = "#E08A30" }
if p.age > 8 { drawing.tint = "#F0C030" }
commands.append(drawing)
@@ -172,19 +212,24 @@ class Dragon {
return commands
}
function heat(self: Dragon, commands: ObjectList, ox: Number, oy: Number, scale: Number): Unit {
// paint 只把本轮 flowText 新命令传入;允许改这些临时字形命令,不改 prepared 资源或 Dragon 原状态。
i = 0
while i < commands.count {
// 外循环逐字形命令处理,内循环逐火焰累加热扰动,多个粒子可共同影响同一字形。
c = commands.at(i)
j = 0
while j < self.flames.count {
p = self.flames.at(j)
dx = c.x - ox - p.x * scale
if math.abs(dx) < 60 * scale {
// 先做横轴范围排除,命中后才计算纵轴差,减少远处粒子的距离计算。
dy = c.y - oy - p.y * scale
if math.abs(dy) < 60 * scale {
// 通过轴向粗筛后求欧氏距离,以下两个条件分别排除近零除法和圆形作用范围外区域。
distance = math.sqrt(dx * dx + dy * dy)
if distance > 0.1 {
if distance < 60 * scale {
// 距离越近、粒子越年轻权重越大;位置向外推开,轻微转动并降低透明度但至少保留 0.3。
weight = (1 - distance / (60 * scale)) * (1 - p.age / 12)
c.x = c.x + dx / distance * weight * 8 * scale
c.y = c.y + dy / distance * weight * 8 * scale
@@ -202,6 +247,7 @@ class Dragon {
}
}
class Manuscript: RectBlock {
// dragon 保存动态业务状态;page 是动画任务 owner;prepared/small/initial 是共享资源,timer 保存最近一次 after 返回的 Task。
dragon: Dragon
page: Object
prepared: Object
@@ -209,58 +255,74 @@ class Manuscript: RectBlock {
initial: Object
timer: Object
function measure(self: Manuscript, mount: Mount, limits: Constraints): MeasureResult {
// source_layout 调用的只读测量,给出不超过 1000×900 的期望大小,宿主仍按完整 Constraints 校验/钳制。
return MeasureResult(math.min(limits.maxWidth, 1000), math.min(limits.maxHeight, 900))
}
function onMount(self: Manuscript, mount: Mount): Unit {
// 宿主挂载通知启动首个 80ms 单次任务,任务归 page、键为 animation;不会在 paint 中调度副作用。
self.timer = ui.after(self.page, "animation", 80, self.tick)
}
// 宿主卸载通知取消最近安排的任务,防止隐藏/退役视图继续无意义地推进动画。
function onUnmount(self: Manuscript, mount: Mount): Unit { self.timer.cancel() }
function tick(self: Manuscript): Unit {
// after 到期调用绑定 tick,先改龙状态,再安排下一次单次任务;这是串行自续约,不是永久后台循环。
self.dragon.step()
self.timer = ui.after(self.page, "animation", 80, self.tick)
}
function paint(self: Manuscript, mount: Mount, bounds: Bounds): DisplayList {
// source_paint 用本轮出现 Bounds 调用,设计画布宽 700,缩放限制为 0.2..1,ox/oy 把设计坐标映射到布局坐标。
scale = math.max(0.2, math.min(1, (bounds.width - 40) / 700))
ox = bounds.x + (bounds.width - 700 * scale) / 2
oy = bounds.y + 30
margin = 45 * scale
text = self.prepared
line = 34
// 窄于 540 时切到预整形的小字和 26 行距,否则用正文字体与 34 行距,不改任何资源对象。
if bounds.width < 540 {
text = self.small
line = 26
}
initialHeight = line * 7
// 首字母图高占七行,宽按素材比例计算;单独矩形排除区给正文留下首字母和右侧间距。
initialWidth = self.initial.width / self.initial.height * initialHeight
art = self.dragon.artwork(ox, oy, scale)
exclusions = ObjectList(g.rectExclusion(ox + margin, oy + margin, initialWidth + 12, initialHeight))
i = 0
while i < art.count {
// 每条龙/火焰精灵按图像形状生成绕排排除区,额外留白随画布缩放,不只用整体外接矩形挡文字。
exclusions.append(g.imageExclusion(art.at(i), 6 * scale))
i = i + 1
}
letters = 0
// 有火焰时请求可逐字母扰动的输出;无火焰时使用普通输出,避免总是拆成大量命令。
if self.dragon.flames.count > 0 { letters = 1 }
// 正文在给定矩形内绕开首字母与所有精灵;可用高度至少为零,避免小窗口产生负尺寸。
drawing = g.flowText(text, ox + margin, oy + margin, 700 * scale - margin * 2, math.max(0, bounds.height - 90 - margin), exclusions, letters)
// 只对新生成的正文命令应用热扰动,原文字符串和预整形资源保持原值。
if self.dragon.flames.count > 0 { self.dragon.heat(drawing.commands, ox, oy, scale) }
// 命令层次为矩形底色 → 首字母 → 正文 → 龙/火焰 → 页脚,列表追加顺序就是绘制顺序。
commands = RectBlock.paint(self, mount, bounds).commands
commands.append(g.sprite(self.initial, ox + margin, oy + margin, initialWidth, initialHeight, 0, 0, 0, 1))
commands.extend(drawing.commands)
commands.extend(art)
footer = g.flowText(hint, bounds.x + 20, bounds.y + bounds.height - 28, math.max(0, bounds.width - 40), 24, ObjectList(), 0)
// 页脚不使用正文排除区,也不应用 heat;把这批命令接到末尾再交宿主统一验证和绘制。
commands.extend(footer.commands)
return DisplayList(commands)
}
}
// 顶层先创建头节,再调用 makeBody 添加十九个身体节;图片只在加载示例时读取,不在动画步中加载。
segments = ObjectList()
headImage = g.loadImage(assets + "dragon-sprites/head.png")
segments.append(Segment(math.float(150), math.float(110), math.float(0), headImage))
function makeBody(): Unit {
// 顶层唯一一次调用,游标沿与待机姿态相同的弧线前进;i=1..19 对应 body-1.png 到 body-19.png。
i = 1
x = math.float(150)
y = math.float(110)
while i < 20 {
// 计算当前节相对于前节的后退位置,加载对应素材并保留在 Segment,随后递增索引。
angle = -i / 19 * math.pi * 0.7
x = x - math.cos(angle) * 30
y = y - math.sin(angle) * 30
@@ -274,24 +336,30 @@ fireImages = ObjectList()
// Layer 2..11: baseline directions differ; these values belong to this artwork.
fireDirections = ObjectList(Direction(-0.50), Direction(-0.30), Direction(-0.55), Direction(0.40), Direction(-1.35), Direction(-1.57), Direction(-1.57), Direction(0.05), Direction(-1.40), Direction(1.12))
function loadFire(): Unit {
// 顶层调用一次,按图片编号 2..11 加载十张火焰;校准表索引用 i-2 转成从零开始。
i = 2
while i <= 11 {
// FireArt 同时保留图片和其自身轴角,之后随机选择整个记录,避免图片和校准值错位。
image = g.loadImage(assets + "fire-sprites/Layer " + g.string(i) + ".png")
fireImages.append(FireArt(image, fireDirections.at(i - 2).angle))
i = i + 1
}
}
loadFire()
// 构造唯一 Dragon,空 flames 列表稍后由 step 填充;初始 lastMove=-10 进入待机路径,seed=42 固定伪随机起点。
dragon = Dragon(segments, ObjectList(), fireImages, g.loadImage(assets + "dragon-sprites/tongue.png"), g.loadImage(assets + "dragon-sprites/wing-front.png"), g.loadImage(assets + "dragon-sprites/wing-back.png"), math.float(150), math.float(110), 0, math.now(), -10, math.float(42))
page = Page()
page.title = "Illustrated Manuscript · Endor"
view = Manuscript(700, 800, 0, "#F4EEE0", dragon, page, bodyText, smallText, g.loadImage(assets + "dropcap.png"), ObjectList())
// 原生 RectBlock 构造参数之后追加六个源字段;timer 的临时初值在挂载通知中换成真正 Task,随后才能 cancel。
view.flex = 1
view.boxWidth = "fill"
page.crossAlign = "stretch"
// 五个连接共用 dragon 的绑定方法,取消与离开走同一清理入口;只注册输入,不在顶层启动 step 循环。
moveConnection = view.on("pointermove", dragon.pointer)
downConnection = view.on("pointerdown", dragon.down)
upConnection = view.on("pointerup", dragon.up)
leaveConnection = view.on("pointerleave", dragon.leave)
cancelConnection = view.on("pointercancel", dragon.leave)
// render 后建立出现,onMount 才启动动画任务;paint 由宿主刷新调用,tick 的状态变化使后续帧重新计算。
page.render(view)
+5
View File
@@ -2,18 +2,21 @@
// 内层视口也可作为世界子项;HUD 在外层 Overlay 中,所以不会随世界相机变换。
// 场景保存世界对象,视口负责有限窗口与相机变换。
count = ui.state(0)
// 同一按钮随 card 在两个视口各出现一次,但只注册这一份回调,点击任意出现都修改同一个 count。
increment = Button("共享计数 +1")
increment.onClick(count.increment)
// 业务卡片带世界 x/y 和边框,count 文字与按钮共同保留同一 state。
card = Column(20, 12, TextBlock("世界里的 UI", 2), ui.textOf(count, "value", 3), increment)
card.boxWidth = 220
card.x = -60
// 这些 x/y 是 Scene2D 世界坐标,不是页面 Row 中的像素位置;每个外层相机分别投影它们。
card.y = 40
card.borderLeft = 2
card.borderColor = "#8CA5B8"
// 有限内层视口看自己的小场景,再以世界坐标放进外层 Scene2D。
inner = CanvasViewport(200, 100, Scene2D(RectBlock(120, 60, 8, "#D4E6D9")))
// inner 自身占外层世界里的有限盒,盒内的小场景另走 inner 的相机和裁剪,输入也需逐层换算。
inner.x = 260
inner.y = 40
// 两个外层视口引用同一 world,卡片/内层视口因此各产生两个出现位置。
@@ -22,6 +25,7 @@ world = Scene2D(card, inner)
left = CanvasViewport(460, 320, world)
left.camera.x = -100
right = CanvasViewport(320, 320, world)
// 两次构造视口默认产生不同 Camera2D,改 right.camera 的字段不会修改 left.camera。
right.camera.x = -80
right.camera.zoom = 0.65
// 如需联动,在 Console 将 right.camera 赋为 left.camera;共享场景本身不会自动共享相机。
@@ -30,6 +34,7 @@ right.camera.zoom = 0.65
views = Row(0, 20, left, right)
hud = Column(16, 8, TextBlock("一个世界,多个视角", 2), TextBlock("滚轮平移 · 空格/中键拖动 · 捏合或 Cmd/Ctrl+滚轮缩放"))
hud.alignSelf = "end"
// HUD 是 views 的 Overlay 兄弟,不是 world 的孩子;其位置受普通布局控制,不参与 world 相机平移缩放。
page = Page()
page.title = "场景与视口"
page.render(Overlay(12, 0, views, hud))
+7
View File
@@ -2,23 +2,28 @@
// 三维内容与普通 Endor 二维控件一起排版,viewport 有限尺寸不限制场景世界坐标。
// 保存左侧视口和共享立方体;动作可改相机位置或真实网格变换。
class SceneActions {
// view 只保存左透视视口,cube 保存两个视口共同引用的网格,两个字段的修改传播范围不同。
view: Viewport3D
cube: Mesh3D
// 把左相机放到 z=6 正面,保持相机既有 target。
function front(self: SceneActions): Unit {
// front.onClick 以零参绑定方法调用,按绝对坐标设置左相机,不重新构造 Scene3D 或清除网格旋转。
self.view.camera.x = 0
self.view.camera.y = 0
self.view.camera.z = 6
}
// 把同一相机移到侧上方,右侧正交相机保持原设置。
function side(self: SceneActions): Unit {
// side.onClick 调用;只设置位置三个分量,保留既有 target 和投影参数。
self.view.camera.x = 6
self.view.camera.y = 2
self.view.camera.z = 0
}
// 修改共享 cube 的欧拉旋转,因此两个视口都看到物体变化。
// rotate.onClick 调用,15 是本次绕 Y 轴增加的角度,重复点击累加,不把旋转每次复位到 15。
function rotate(self: SceneActions): Unit { self.cube.rotate(0, 15, 0) }
// 示范 Event.hit.mesh 的真实托管网格材质写入;此文件尚未把 select 注册到视口。
// 这是供后续命中事件注册的入口,须由提供 hit.mesh 的网格命中事件调用;本文件的三个按钮均不调用它。
function select(self: SceneActions, event: Event): Unit { event.hit.mesh.color = "#6B9B81" }
}
// 先构造并变换两个 Box3D,再由 Group3D 组成场景节点;几何与相机是不同对象。
@@ -29,6 +34,7 @@ small = Box3D(0.7, 0.7, 0.7, "#DBA36E")
small.x = 1.8
small.z = -0.8
group = Group3D(cube, small)
// group 保留两个网格的变换层级,两视口复用下面同一个 scene,不分别创建立方体副本。
// 薄盒作地面,方向光与 ambient 一起影响材质颜色,不是二维背景矩形。
floor = Box3D(6, 0.08, 4, "#D8DEE6")
floor.y = -1.1
@@ -40,6 +46,7 @@ perspective = Viewport3D(480, 360, scene)
perspective.camera.z = 6
orthographic = Viewport3D(320, 360, scene)
orthographic.camera = OrthographicCamera()
// height 表示正交相机可见世界高度,不是右视口 360 的逻辑像素高度。
orthographic.camera.height = 5
orthographic.camera.x = 4
orthographic.camera.y = 2
+5
View File
@@ -2,13 +2,16 @@
// 圆外部分可落到父容器监听器;按下与释放须经相同合法目标复核。
// 扩展矩形的绘制、命中和事件方法,用同一个 hits 状态观察交互结果。
class CircleTarget: RectBlock {
// hits 由下面顶层 state 提供,源命中只读它所需的几何,计数写入留给 onEvent。
hits: Object
// point 已转换到该出现位置局部坐标;使用圆心(40,40)、半径40,而不是整个 160x80 外框。
function hitTest(self: CircleTarget, mount: Mount, point: Point): Bool {
// source_hit 在候选出现的命中阶段调用,point 已转换为局部坐标,不应再减 geometry.x/y。
return point.inCircle(40, 40, 40)
}
// 把原生命令宽度缩为 80、圆角半径设为 40,得到与 hitTest 对应的圆形区域。
function paint(self: CircleTarget, mount: Mount, geometry: Bounds): DisplayList {
// source_paint 调用此覆盖;修改新生成的第一条矩形命令,不把共享对象的原生 width 从 160 改成 80。
drawing = RectBlock.paint(self, mount, geometry)
drawing.commands.at(0).width = 80
drawing.commands.at(0).radius = 40
@@ -16,6 +19,7 @@ class CircleTarget: RectBlock {
}
// 圆内点击递增自身计数并停止向祖先传播;父容器不会为同一次点击再递增。
function onEvent(self: CircleTarget, event: Event): Unit {
// 此示例的点击分发选中圆后调用对象方法;stopPropagation 只阻止后续祖先组,不撤销已经执行的捕获处理。
self.hits.increment()
event.stopPropagation()
}
@@ -24,6 +28,7 @@ hits = ui.state(0)
// 父监听器单独计数;它和圆形目标显示在同页,便于比较穿过透明区的输入。
background = ui.state(0)
circle = CircleTarget(160, 80, 0, "#237A45", hits)
// 布局仍给 circle 原生的 160×80 盒,只有绘制和形状命中缩成左侧圆;透明右半部并非不存在的布局区域。
root = Column(24, 16, circle, TextBlock("点击圆内计入圆;透明右半区域交给父容器"), TextBlock("圆内点击"), ui.textOf(hits, "value"), TextBlock("父容器点击"), ui.textOf(background, "value"))
// 订阅在父 Column 上,圆外有效区域可回退到父目标;源命中只读检查不执行这些业务回调。
connection = root.on("click", background.increment)
+6
View File
@@ -2,9 +2,11 @@
// 同一 rect 出现两次,两份命令随同一 tint 更新;业务身份共享,几何按 Mount 分开。
// 原生矩形测量不变,仅将绘制颜色切换为源字段 tint。
class TintRect: RectBlock {
// 源颜色策略与原生构造颜色分别保存;两个出现都读取同一 tint,但用各自 geometry 生成命令。
tint: String
// 从原生基类取得当前出现位置的矩形命令,再修改本次返回列表中的颜色并交回。
function paint(self: TintRect, mount: Mount, geometry: Bounds): DisplayList {
// source_paint 在只读计算阶段调用,基类返回本轮新列表,修改其中命令不等于修改已有业务状态。
drawing = RectBlock.paint(self, mount, geometry)
drawing.commands.at(0).color = self.tint
return drawing
@@ -15,6 +17,7 @@ class Badge: TextBlock {
background: String
// 先完整填写 roundedRect 命令,再取原生文字命令改成白色;列表顺序决定先画背景后画文字。
function paint(self: Badge, mount: Mount, geometry: Bounds): DisplayList {
// Badge 的源覆盖构造一条新背景命令,再组合原生文字命令;并未创建额外的背景 Block 或 Mount。
fill = PaintCommand()
// 命令 kind 决定宿主解码所需字段,坐标/宽高来自本次 Mount,radius/color 由业务策略提供。
fill.kind = "roundedRect"
@@ -27,6 +30,7 @@ class Badge: TextBlock {
// 复用原生文字塑形和换行所需参数,避免手工文字命令漏掉边界。
text = TextBlock.paint(self, mount, geometry).commands.at(0)
text.color = "#FFFFFF"
// ObjectList 的先后决定遮盖次序,返回时宿主统一验证命令字段和范围。
return DisplayList(ObjectList(fill, text))
}
}
@@ -35,11 +39,13 @@ class RecolorButton: Button {
target: TintRect
// 事件阶段可修改已有业务字段;依赖跟踪检测 tint 变化后重绘两个出现位置。
function onEvent(self: RecolorButton, event: Event): Unit {
// 分发器调用 Button 子类的对象方法,无需另写 button.on;这里可写 target,paint 中只能读它。
self.target.tint = "#526AC7"
}
}
// 两次使用 rect 是同一对象,Badge 与按钮独立;根容器只组合它们,不复制业务数据。
rect = TintRect(200, 60, 12, "#DDEEFF", "#ED6A5A")
// Badge 的末尾字符串是新增 background 字段;TextBlock 的原生可选颜色省略,随后 paint 将文字改为白色。
badge = Badge("Endor 源码正在绘制这个背景", 2, "#237A45")
button = RecolorButton("通过对象方法改变绘制颜色", rect)
root = Column(24, 16, TextBlock("源码 paint 进入真实窗口", 2), rect, rect, badge, button)
+13
View File
@@ -3,9 +3,11 @@
// 整个文件作为一次完整源码输入提交;状态只存在本次 VM,会话重置后不保留。
// 为 Column 增加期望宽度字段,使手工表格各列对齐,而非让文字自然宽度决定列边界。
class GradeCell: Column {
// 自有源字段控制期望列宽;每个调用包装不同内容对象,父约束可进一步限制实际分配。
width: Number
// 先保留 Column 的自然高度,再把新测量结果宽度设为字段值,最终仍由父约束协商。
function measure(self: GradeCell, mount: Mount, constraints: Constraints): MeasureResult {
// source_layout 调用覆盖,Column.measure 返回新临时结果;改 size.width 不修改 student 或其绑定文字。
size = Column.measure(self, mount, constraints)
size.width = self.width
return size
@@ -15,6 +17,7 @@ class GradeCell: Column {
class GradePanel: Column {
// 按本次 geometry 生成白色圆角底板;不重绘或复制子项命令,后代由统一遍历处理。
function paint(self: GradePanel, mount: Mount, geometry: Bounds): DisplayList {
// source_paint 的只读入口创建新命令,不在绘制阶段修改成绩/表格;绘制顺序由父背景后接孩子命令保证。
fill = PaintCommand()
fill.kind = "roundedRect"
fill.x = geometry.x
@@ -28,6 +31,7 @@ class GradePanel: Column {
}
// 姓名/学号和各科成绩/状态是业务字段;数值修改受 Number 声明检查。
class Student {
// 同一 Student 可由多个 gradeRow 引用,响应式成绩/状态绑定始终读取原对象,没有每行一份成绩副本。
name: String
number: String
chinese: Number
@@ -37,10 +41,12 @@ class Student {
}
// 用统一无 padding/gap 的单格容器包装任意 Block,末尾 width 是源字段构造参数。
function gradeCell(content: Block, width: Number): Block {
// gradeRow 和 gradeHeader 调用,传入孩子之后的 width 是 GradeCell 源字段,不能混进 Column 视觉子项列表。
return GradeCell(0, 0, content, width)
}
// 姓名/学号直接取初值,成绩和状态用响应式 textOf;行末分隔线与固定列宽保持表格结构。
function gradeRow(student: Student): Block {
// 顶层 allGradeRows 调用六次,attentionGradeRows 另为 studentLin 调用一次;视觉树不同,学生业务身份可相同。
return Column(0, 12,
Row(0, 0,
gradeCell(TextBlock(student.name), 150),
@@ -53,6 +59,7 @@ function gradeRow(student: Student): Block {
}
// 保存全部/复核两棵现成子树与可替换 table,同时持有要复核的真实 Student。
class GradeCenter {
// all/attention 两棵子树都由模型强引用保留,切掉某个展示根不会丢失它;student 是要复核的 studentLin。
table: Column
all: Column
attention: Column
@@ -61,16 +68,19 @@ class GradeCenter {
message: String
// 替换稳定槽0的内容为全部行,复用已有学生,不重新请求/重建数据。
function showAll(self: GradeCenter, event: Event): Unit {
// showAllGrades 的绑定事件入口,替换容器当前槽 0 内容,不把 all 的孩子逐个拷贝到 table。
self.table.replace(0, self.all)
self.message = "正在查看全部 6 位学生"
}
// 切换到预先构造的复核行;这是特定示例子树,不是动态过滤算法。
function showAttention(self: GradeCenter, event: Event): Unit {
// showAttentionGrades 调用,选中既有 attention 子树;pending 变成零也不会自动删除这棵预建视图。
self.table.replace(0, self.attention)
self.message = "林沐的数学成绩有一条复核记录"
}
// 写预设数学成绩68及状态,清待复核数;相关绑定在两个视图都读同一 studentLin。
function review(self: GradeCenter, event: Event): Unit {
// reviewGrade 事件入口写入同一学生,隐藏的另一行也通过绑定观察新值;没有遍历所有行手工改文字。
self.student.math = 68
self.student.status = "已复核"
self.pending = 0
@@ -78,6 +88,7 @@ class GradeCenter {
}
// 恢复初始学生值/计数并显示全部列表,便于重复观察同一操作。
function reset(self: GradeCenter, event: Event): Unit {
// resetGrades 派发时恢复字段并切回 all;保留 Student、GradeCenter 和按钮身份,便于继续点击演示。
self.student.math = 58
self.student.status = "待复核"
self.pending = 1
@@ -94,6 +105,7 @@ studentSu = Student("苏映雪", "2026005", 88, 92, 90, "已确认")
studentLu = Student("陆景行", "2026006", 79, 84, 87, "已确认")
allGradeRows = Column(0, 14, gradeRow(studentLin), gradeRow(studentChen), gradeRow(studentXu), gradeRow(studentZhou), gradeRow(studentSu), gradeRow(studentLu))
attentionGradeRows = Column(0, 14, gradeRow(studentLin))
// gradeTable 始终只包含一个内容槽,后续 replace 在这个边界换整棵视图;表头独立放在外层 GradePanel。
gradeTable = Column(0, 0, allGradeRows)
// table 最初含一个稳定子槽,后续 replace(0,...) 正是切换这个槽。
gradeCenter = GradeCenter(gradeTable, allGradeRows, attentionGradeRows, studentLin, 1, "正在查看全部 6 位学生")
@@ -106,6 +118,7 @@ showAllGrades.on("click", gradeCenter.showAll)
showAttentionGrades.on("click", gradeCenter.showAttention)
reviewGrade.on("click", gradeCenter.review)
resetGrades.on("click", gradeCenter.reset)
// 四次注册不立即调用方法,所以初始化仍显示全部学生、待复核数 1 和林沐数学 58。
// 表头复用与数据行完全相同的列宽,摘要仅 pending 响应式,6/3是固定示例统计。
gradeHeader = Row(0, 0,
gradeCell(TextBlock("学生", 1, "#7A8390"), 150),
+7
View File
@@ -3,11 +3,13 @@
// 面板内容仍是完整 Endor UI,可共享对象、绑定、源视觉协议与嵌套视口。
// 分别持有外层三维视口、面板变换和面板内二维画布,避免一次动作同时驱动多层相机。
class WorldActions {
// 三个引用分别指向观察相机所在视口、三维面板实体和内层二维视口,不把它们的坐标系混用。
view: Viewport3D
panel: Panel3D
canvas: CanvasViewport
// 重置三维相机位置与观察目标,不改变面板或内层画布业务状态。
function reset(self: WorldActions): Unit {
// reset.onClick 派发零参绑定方法,按绝对值恢复外层相机位置/target;不会调用 canvas.fitView。
self.view.camera.x = 0
self.view.camera.y = 0.5
self.view.camera.z = 7
@@ -16,13 +18,16 @@ class WorldActions {
self.view.camera.targetZ = 0
}
// 只旋转 Panel3D 平面,面板内 UI 树仍用自己的逻辑宽高。
// turn.onClick 调用,每次给面板世界变换增加 15 度 Y 旋转,不修改 UI 分辨率或子树字段。
function turn(self: WorldActions): Unit { self.panel.rotate(0, 15, 0) }
// 找到画布当前 Mount,按该出现位置的有限尺寸 fitView,而非用外层三维视口大小。
// fit.onClick 在挂载后调用;本例 canvas 只在一个面板出现,at(0) 选择其有效 Mount,再按该出现计算相机适配。
function fit(self: WorldActions): Unit { self.canvas.mounts().at(0).fitView() }
}
count = ui.state(0)
increment = Button("点击:世界里的真实按钮")
increment.onClick(count.increment)
// 这个按钮在 Panel3D 内,后面的 reset/turn/fit 在外层页面;它们共享 VM,但输入需要不同坐标转换路径。
// 二维场景卡片使用带符号世界坐标;canvas 再提供有限可见区域和独立 camera。
card = Column(10, 6, TextBlock("CanvasViewport", 1), RectBlock(180, 26, 6, "#9CB8A8"))
card.boxWidth = 240
@@ -36,6 +41,7 @@ ui_root.crossAlign = "stretch"
panel = Panel3D(4, 3, ui_root)
panel.uiWidth = 320
panel.uiHeight = 240
// panel 的 x/rotationY 改三维平面变换;UI 仍在 320×240 的逻辑区域里布局,不把世界单位当作字形像素。
panel.x = -1.2
panel.rotationY = 15
cube = Box3D(1.4, 1.4, 1.4, "#7B9CB7")
@@ -51,6 +57,7 @@ view = Viewport3D(960, 520, scene)
view.flex = 1
view.camera.y = 0.5
view.camera.z = 7
// 控制器保存已创建的三层对象,注册回调不会提前执行重置、转动或 Mount 查询。
actions = WorldActions(view, panel, canvas)
reset = Button("重置摄像机")
reset.onClick(actions.reset)