顽皮的画布
用于浏览器游戏的React界面，由Yoga WebAssembly布局和WebGL渲染提供支持。
用四种类型的原语组合hud、菜单和目录： 视图， 文本， 图像 和 行． 当渲染器在WebAssembly中计算flexx布局并使用清晰的MSDF文本绘制批处理GPU原语时，使用React状态、效果和上下文。
控制 按钮， 开关， 滑块， 选项卡， 选项卡， 对话框 和 ScrollArea 组件在离开它们的布局时共享交互行为， 游戏的颜色和内容。探索 组件目录。
0.7.0版本增加了controlled TextInput 和 文本区域 本地的 最顶层的表单面板和对话框的编辑器。看到 本地编辑合同 对于字体，分层，构图和资格限制。这些字段需要 Ludic-canvas 0.7.0或更高版本。
0.9.0版本包含一个 实验便携式核心和macOS证明： 同样的React组件运行在Hermes、native Yoga和Skia/Metal上。这项工作 仍然是实验性的。看到 架构和构建指令 和 资格的结果． Android, iOS, Windows 和Linux主机仍然是未来的工作。
安装
npm包包括JavaScript、TypeScript声明、预编译的Yoga反应器、默认的OFL字体图集、可移植字体图集编译器和许可声明。
npm install ludic-canvas [email protected]
版本使用中描述的变更集版本- pr工作流 文档/ RELEASING.md。
启动一个项目（0.4.0+）
npx ludic-canvas@latest init my-game --template canvas2d
cd my-game
npm install
npm run dev
选择 --template three Three.js的世界。两个启动器都包含一个透明的
UI覆盖，控制HUD，应用程序拥有的仿真/帧循环，响应
画布大小，许可字体，开发/构建前的字体生成，以及
资源拆卸。初始化器接受新目录或空目录
自动安装依赖项。使用 npm run build 生成 dist/。
取代 fonts/Interface.ttf 和编辑 ludic-canvas.fonts.json 带上你自己的
授权的TTF、OTF、WOFF或WOFF2字体。导入的atlas url支持部署
在URL前缀下。看到 初始化器指南。
共同控制
import { useState } from 'react';
import { Switch, Text } from 'ludic-canvas';
function Hints() {
const [enabled, setEnabled] = useState(true);
return (
<Switch label="Navigation hints" checked={enabled} onCheckedChange={setEnabled} style={{ padding: 16 }}>
<Text>{enabled ? 'Hints on' : 'Hints off'}</Text>
</Switch>
);
}
值仍然由应用程序控制。滑动条渲染函数接收
归一化比例自定义轨道/拇指。选项卡管理一个键盘选项卡停止和
跳过禁用的条目。对话框通过嵌套隔离输入并恢复焦点
范围。ScrollArea提供垂直滚轮/触摸滚动和焦点显示。
useUIRoot() 访问内部的所属根 ui.render();分开的根保持
他们自己的焦点，React状态和资源。没有使用全局活动根。
字体图集CLI （0.2.0+）
该包包含一个可移植的CLI：
npx ludic-canvas fonts --init
# Set the font source paths in ludic-canvas.fonts.json
npx ludic-canvas fonts --config ludic-canvas.fonts.json
{
"$schema": "https://libraries.ludic-canvas.victorqueiroz.dev/font-atlas.schema.json",
"output": "public/fonts",
"fonts": [
{
"name": "interface",
"source": "fonts/Interface.woff2",
"size": 48,
"distanceRange": 6
}
]
}
输入为单面轮廓 TTF， OTF， WOFF和WOFF2 字体，包括变量
配置了轴标记的字体，如 "variations": { "wght": 600 }。
路径是相对于配置文件的。命令行生成MTSDF PNG文件，
JSON指标和缓存清单。通过注册PNG/JSON createUI({ fonts })。
安装后不需要本机编译器、外部可执行文件或网络连接。
将CLI命令添加到您的项目中 predev 和 prebuild 生成的脚本
只有当输入改变时。使用 --force 重建。看到
字体命令行指南
用于字符覆盖，可变字体和诊断。
第一个界面
在StackBlitz中打开最小计数器 或者运行 独立的例子． 它安装已发布的 并使用其捆绑的字体和布局WASM，而不使用本地构建工具。 看到 已测试的消费者配置 发展 启动和浏览器验证。
给画布一个非零的CSS宽度和高度。然后使用自动JSX编译：
import { createUI, View, Text } from 'ludic-canvas';
const ui = await createUI({ canvas });
ui.render(
<View style={{ padding: 24, gap: 12 }}>
<Text style={{ fontSize: 28 }}>Ready to play</Text>
<View
label="Start game"
onPress={() => startGame()}
style={{ padding: 16, background: '#526dff', borderRadius: 8 }}
>
<Text>Start game</Text>
</View>
</View>,
);
// On scene teardown:
ui.destroy();
可玩性整合示例
这个 玩画廊 提供可选择的缩略图，一个活动的游戏视窗和集成说明，为每个例子。
轨道继电器 是一款带有Canvas 2D世界和透明Ludic Canvas HUD的小型快递游戏。它包括货物收集和交付，碰撞，增强，暂停和重放，响应清单和键盘/触摸控制。
这个 示例源 仅使用公共库导出。它的接口和任务模块分别定义了一个字体族和一个CLI配置。应用程序根由两者组成 FontSource 值，在React外部保持模拟状态，并驱动 ui.frame(now) 从游戏循环来看。
npm run fonts:game # regenerate Oxanium and Space Mono atlases
npm run dev # open /play/ or play inside the homepage
体系结构
React components and hooks
↓
Retained host tree + input
↓
Yoga 3.2.1 layout in WebAssembly
↓
Painter, animation and hit testing
↓
WebGL 1 batches + MSDF font atlases
该库拥有布局、渲染、动画和输入。你的应用程序拥有游戏状态、模拟、持久性、音频和资产。提供图像url或解析器、注册字体图集和自定义主题令牌。没有绑定游戏模式、资产目录或ECS。
默认启动自动绘图。对于游戏拥有的循环，通过 autoStart: false 并调用 ui.frame(now) 游戏渲染后。透明的覆盖画布独立于游戏的渲染器工作。高级WebGL 1集成可以提供共享上下文；UI更改GL状态，引擎必须在下一次通过之前重置其状态缓存。
发展
Node 24或更新版本：
npm ci
npm run dev # documentation and interactive examples
npm run check # types, real WASM/React tests, docs, distribution audit
npm run format:check
npx playwright install --with-deps
npm run test:browser # Chromium, Firefox, WebKit and mobile emulation
npm pack # installable release tarball
该文档使用Vite和静态HTML作为可抓取的指南和从发出的TypeScript声明生成的API引用。它的实例使用了构建包的公共输出。
看到 CONTRIBUTING.md 对于源映射，生成的文档， 集中浏览器检查，CI故障排除和证据程序。的日期为 会话切换 记录验证状态和剩余工作。
重新构建可选的本地工具：
npm run toolchain -- --llvm /path/to/llvm
npm run wasm
npm run fontgen:wasm
npm run fonts:example
Yoga使用c++ 23， CMake 3.28+，原始Clang/LLVM和wasm-ld，并使用sha -256固定的Yoga和WASI工具链下载。不使用Emscripten。可移植字体编译器将固定的msdf-atlas-gen、FreeType和Brotli源代码构建到WASI命令中。消费者使用Node运行包含的编译器，不需要本地工具。
出版
运行 npm run changeset 对于可发布的行为变化。合并到 main 打开或
更新一个版本PR。将PR通过npm OIDC发布的版本与
来源，在Linux/macOS/Windows检查通过后。工作流创建标记和
GitHub发布和跳过npm上已经存在的版本。
看到 文档/ RELEASING.md 对于常规放行程序，
npm run verify:release、部署验证和历史所有者设置。
没有npm令牌存储在GitHub机密中。
兼容性和范围
Ludic Canvas瞄准桌面和手机浏览器游戏。React 19.3.1是测试的对等版本；react-reconciler 0.34.0被固定，因为它的主机API不稳定。浏览器需要WebGL 1， WebAssembly SIMD/bulk-memory， createImageBitmap和Pointer Events。
运行时支持捕获的指针/键事件、垂直滚轮/触摸滚动、范围热键、模态焦点范围、空间焦点导航、DOM控制/组语义、礼貌的实时通知、文本缩放和减少运动。镜像是一个有限的辅助工具，而不是一个完整的语义文档。
文本使用预烤的字形，地图集对字距和贪婪包装。一串或
有序数组 fontFamily 选择注册面；每个字形都使用第一个
脸上含着它。所有选择的面都共享一个基线，而回退指标可以
增加行高。集 fontKerning: 'none' 禁用配对调整。
Complex-script/GPOS塑形，bidi，石墨烯感知包装，可编辑的画布文本，
共享的WebGL 2上下文和本地引擎绑定仍然没有实现。到
每个根支持四个字体地图集。看到 生产审核
和 支持矩阵。
const ui = await createUI({
canvas,
fonts: [interfaceFont, symbolsFont],
onFontDiagnostic: (diagnostic) => console.warn(diagnostic.message),
});
ui.render(<Text style={{ fontFamily: ['interface', 'symbols'] }}>Café · Ready</Text>);
使用你的名字 FontSource 值。缺失的字形变成 ? 在
主要面对和可以产生一个可选择的诊断，每个代码点/订购一次
链，上限为每个根1024个报告。当改变字符集时再生一个地图集
报道。CLI提取遗留文件 kern 表;只有gpos的字体可以输出零
对。没有字距数组的现有atlas JSON仍然可用。
这个 性能实验室 运行固定的UI工作负载并下载带有源/环境元数据的原始示例。 看到 测量限制和获取说明。
这个 路线图 定义专用排版里程碑和 物理设备鉴定协议 分离 来自硬件和辅助技术证据的自动正确性检查。
许可证
MIT©Victor Queiroz。绑定的字体使用SIL开放字体许可证。看到 THIRD_PARTY_NOTICES.md 和 许可/。
3D样例工程
玩《红隼调查》 或者运行 独立实例工程． 它结合了一个程序化的3 .js世界和一个完全自定义的Ludic Canvas界面：投影站点标签、任务卡、遥测、小地图、相机控制、模态菜单和移动站点选择器。
cd examples/kestrel-survey
npm install
npm run dev
大集合
VirtualList 提供具有稳定键的固定高度单选择集合；
扫描，控制选择和逻辑键盘/手柄焦点。普通的
ScrollArea 区域可以公开独立类型的滚动句柄。看到
收集指南，
完整的合同，以及里面4000条记录的档案
红隼调查。
这个 性能实验室
比较匹配的保留/窗口工作负载并保留原始测量值。
浏览器根自动使用包含渲染画布块的本地溢出
对于支持的滚动面板。浏览器提供动力，而React， Yoga
应用程序的框架循环保留它们现有的所有权。使用
scrollMode="canvas" 按地区或 scrollMode: 'canvas' 在 createUI 选择
帆布表示。共享上下文，自定义手势和不支持的布局
自动后退。看到 滚动的合同 为
支持边界、贴图预算和快照定时。