用JSON定义游戏界面：FlatUI序列化功能完整上手教程
用JSON定义游戏界面FlatUI序列化功能完整上手教程【免费下载链接】flatuiEfficient Immediate Mode UI for Games项目地址: https://gitcode.com/gh_mirrors/flatu/flatuiFlatUI 是 Google 开源的高效即时模式Immediate Mode游戏 UI 库主打轻量、快速、零状态管理的界面渲染方案。而它的序列化功能Serialization更是让开发者可以用 JSON 直接定义游戏界面把界面布局与 C 代码彻底分离堪称游戏开发者的界面配置神器。这篇教程将带你从零上手 FlatUI 序列化学会用 JSON 快速搭建游戏菜单、配置控件、绑定事件并扩展自定义控件全程无需反复编译即可调整界面。什么是 FlatUI 序列化功能传统即时模式 UI 中界面代码和逻辑代码混在一起改一个按钮位置都要重新编译。FlatUI 序列化功能改变了这一切它借助FlatBuffers序列化框架允许你用一份 JSON 文件描述整个游戏界面控件、布局、尺寸、事件运行时再解析加载、渲染显示。它的核心价值在于界面与代码解耦改 UI 文案、颜色、布局只改 JSON不动 C 代码天然支持多人协作策划、美术可以直接编辑 JSON程序员专注逻辑低开销高性能FlatBuffers 序列化后的二进制数据无需解析即可直接读取契合游戏对性能的苛刻要求支持动态数据与自定义控件可注册运行时可变的变量也可扩展专属控件。FlatUI 序列化核心原理JSON 到界面的一次旅行整个流程可以概括为三步写 JSON → 用 Schema 解析成二进制 → 运行时反序列化渲染。负责这一切的骨架是 flatui.fbsFlatBuffers Schema 文件它定义了界面的语法规则。其中FlatUIElement是核心表结构包含了id、type、layout、text、size、margin、offset、horizontal、vertical等字段而Type枚举则列出了 FlatUI 内置支持的控件类型控件类型用途常用字段Label文本标签text、ysizeTextButton文本按钮text、size、marginImage图片显示texture、ysizeImageButton图片按钮texture、sizeEdit文本输入框ysize、size_2fSlider滑动条texture、size_2f、bar_sizeCheckBox复选框texture、textScrollBar滚动条texture、size、bar_sizeGroup容器分组layout、horizontal、vertical、offsetSetVirtualResolution设置虚拟分辨率virtual_resolution关于 Schema 的完整字段定义可以参考 flatui.fbs 中的注释说明。快速上手用 JSON 定义第一个游戏界面我们直接看 FlatUI 自带的序列化示例 first_menu.json它定义了一个居中的垂直布局菜单包含标题、按钮和输入框{ elements: [ { type: flatui_data.Type.SetVirtualResolution, id: virtual resolution, virtual_resolution: 1000 }, { type: flatui_data.Type.Group, id: first menu group, layout: VerticalLeft, horizontal: Center, vertical: Center, elements: [ { type: flatui_data.Type.Label, id: first menu label, text: Welcome to the first menu! :D, ysize: 40 }, { type: flatui_data.Type.Edit, id: first menu edit text, ysize: 40, size_2f: { x: 0, y: 0 } } ] } ] }这段 JSON 传达了几个关键信息type指明控件类型如Label、Group、Editid是控件的唯一标识后续绑定事件、注册动态数据全靠它layout / horizontal / vertical控制布局方向与对齐方式Center表示居中elements支持无限嵌套实现树形界面结构与 C 中的StartGroup / EndGroup逻辑一一对应。在 C 中加载并渲染 JSON 界面JSON 写好了接下来用 C 把它加载进游戏。完整的可运行示例在 flatuiserializationsample.cpp核心流程如下加载文件读取 JSON、自定义控件 Schema 和主 Schema解析生成二进制用flatbuffers::Parser结合 Schema 把 JSON 编译成 FlatBuffer 二进制数据创建界面调用CreateFlatUIFromData()传入二进制数据渲染循环把创建函数传入flatui::Run()每帧执行。flatbuffers::Parser parser; parser.Parse(schema.c_str(), include_directories); // 解析 Schema parser.Parse(first_menu_json.c_str()); // 解析 JSON auto* data parser.builder_.GetBufferPointer(); // 拿到二进制数据 Run(assetman, fontman, input, []() { flatui::CreateFlatUIFromData(data, assetman, event_handler); });CreateFlatUIFromData是序列化 API 的核心入口其完整签名定义在 flatui_serialization.h接受三个参数FlatBuffer 数据、用于纹理渲染的AssetManager可选、以及事件处理器FlatUIHandler可选。事件绑定与动态数据让界面活起来静态界面没有意义FlatUI 序列化通过事件绑定和动态数据让界面与游戏逻辑联动。事件处理事件处理器是一个std::function接收事件、控件 ID 和动态数据三个参数。示例代码中通过 lambda 包装后传入CreateFlatUIFromDataauto event_handler { EventHandler(e, id, dynamic_data, menu_id); };在EventHandler内部按控件id分发逻辑例如监听change menu button的kEventWentUp松开事件切换菜单实现两个菜单之间的来回切换。动态数据注册输入框里的文字是运行时可变的需要用RegisterStringData把它和 JSON 中的控件 ID 绑定std::string edit_text_box(Edit me!); flatui::RegisterStringData(first menu edit text, edit_text_box);FlatUI 提供了一套完整的注册函数RegisterIntData、RegisterFloatData、RegisterBoolData、RegisterVec2Data、RegisterVec4Data等对应DynamicData联合体中的各种数据类型全部声明在 flatui_serialization.h。注意注册的指针必须比界面的生命周期更长否则会引发悬垂指针。自定义控件扩展 FlatUI 的专属武器内置控件不够用时FlatUI 序列化还支持自定义控件。步骤很简单定义枚举在自定义 Schema如 custom_widgets.fbs中声明控件类型实现渲染函数编写一个符合CustomWidget签名的函数用element中的数据调用 FlatUI 绘制 API注册控件调用RegisterCustomWidget(type, widget)把类型与函数绑定。void ChangeMenuButton(const flatui_data::FlatUIElement* element, fplbase::AssetManager* assetman, flatui::FlatUIHandler event_handler, flatui::DynamicData* dynamic_data) { flatui::StartGroup(flatui::kLayoutVerticalLeft); flatui::ColorBackground(fplbase::LoadVec4(...)); flatui::Event e flatui::TextButton(element-text()-c_str(), element-size()); flatui::EndGroup(); event_handler(e, element-id()-str(), dynamic_data); } flatui::RegisterCustomWidget(custom_widgets::Type_ChangeMenuButton, ChangeMenuButton);自定义控件还能通过attributes字段接收 JSON 中传入的任意参数颜色、尺寸、对齐方式等灵活性极高示例中的Change Menu按钮就是典型应用。调试技巧与常见问题JSON 写错了怎么办FlatUI 内置了错误输出机制默认最多打印 10 条错误可通过SetErrorOutputCount()调整flatui::SetErrorOutputCount(flatui::kNoErrorOutputLimit); // 输出所有错误常见坑位提醒JSON 格式不合法示例代码在Parse失败时会直接报错退出务必检查括号与逗号texture 找不到渲染图片控件时确保AssetManager中已加载对应纹理资源id 冲突或遗漏事件绑定和动态数据都依赖id命名要全局唯一Schema 版本不一致JSON 字段必须与flatui.fbs版本匹配否则解析报错。总结什么时候该用 FlatUI 序列化如果你正在开发游戏且满足以下任一场景强烈建议尝试 FlatUI 序列化功能需要频繁调整界面布局希望免编译热改 UI团队中有策划或美术参与界面配置需要动态生成菜单、弹窗等结构化界面追求极低开销的序列化方案FlatBuffers 天然零拷贝。上手方式也很简单将仓库https://gitcode.com/gh_mirrors/flatu/flatui克隆到本地直接运行sample/serialization目录下的示例工程对照 first_menu.json、second_menu.json 和 flatuiserializationsample.cpp 边改边看很快就能掌握用 JSON 定义游戏界面的全部技巧【免费下载链接】flatuiEfficient Immediate Mode UI for Games项目地址: https://gitcode.com/gh_mirrors/flatu/flatui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
