Flecs Rust API 是什么？

Rust API 是围绕 Flecs C API 的包装器。该 API 设计为为 Rust 开发者提供直观且流畅的接口，以充分利用 Flecs 的全部潜力。

它基于 V4 Flecs 版本，相关博客文章可在这里找到。

Flecs ECS 是什么？

Flecs 是一个快速且轻量级的实体组件系统，可以让您使用数百万个实体（加入Discord！）构建游戏和模拟。以下是该框架的一些亮点：

• 快速且可移植。由于 Flecs C 内核，它具有多种语言的绑定，包括 C++、C#，现在还有 Rust！
• 是第一个完全支持 实体关系 的开源 ECS！
• 对 层次结构 和 预制体 提供快速原生支持
• 在浏览器中运行（Rust 指令待定/进行中）
• 缓存友好的 架构/SoA 存储，每帧可以处理数百万个实体
• 支持拥有数百个组件的实体和具有数万个架构的应用程序
• 自动组件注册，无需额外配置即可在共享库/DLL中工作
• 使用 查询 编写免费函数或在 系统 中自动运行代码
• 使用快速无锁调度器在多个 CPU 核心上运行游戏
• Flecs 已经过大量测试，仅在核心库中就有超过 8000 个测试，并在 AAA 引擎中使用。Rust API 本身也有 500+ 个测试，并且还在不断增加。
• 集成了（WIP Rust）反射框架，以及JSON序列化器和运行时组件的支持
• 强大的查询语言，支持连接和继承
• 统计插件，用于分析ECS性能
• 基于Web的UI，用于监控和控制您的应用程序（演示，代码）

如何开始？

将以下内容添加到您的Cargo.toml

[dependencies]
flecs_ecs = "0.1.1" 

然后开始编写代码！

请确保查看Rust文档（即将推出改进），Flecs文档，以及示例目录中的70多个示例。

以下是一些Flecs与以下crate的集成示例

• WGPU用于渲染
• winit用于窗口
• vello用于光栅化
• parley用于文本

请参阅此处的演示

状态：Alpha版本

该项目处于Alpha版本发布阶段，其中Flecs的核心功能和一些插件已被移植，并可用于今日。虽然已经对当前的API进行了很多思考，但它仍然处于实验阶段。该项目旨在在解决所有健全性/安全性问题并最终确定API以及Flecs的所有功能时达到稳定。我们鼓励您探索、测试并提供反馈，但请注意，在继续完善API和添加新功能的过程中，可能会出现潜在的bug和重大变更。

此库在Flecs V4版本发布日期公开。

安全性

尚未解决的一个重要安全问题是有多个别名指向同一个组件。这是一个已知问题，正在解决中。将通过表列锁定机制来解决。

性能

根据初始基准测试和测试，Rust API的性能与C级性能相当，除了在Rust环境中使用API时引入了开销（例如get性能）。但是，计划在将来进行性能改进。

进度

有关详细功能进度，请访问问题页面。

• 核心库
• 插件（Meta + Json + Script处于WIP，预计于8月底发布，实验阶段更早）
• 文档（大多数函数都有文档，并包含一个C++别名。Flecs文档网站包含Rust代码。剩余的百分比用于添加主要是doc测试示例和精炼Rust文档页面。）
• 测试套件（实体、查询、观察者系统测试用例已完成）
• 示例 对于当前的功能集，所有示例都已完成。

目标

计划是匹配 C++ API 的功能对等性，从核心库（已完成！）开始，同时进行全面文档化、测试和解决可能出现的任何安全问题。项目旨在为 Flecs 提供一个安全、惯用且高效的 Rust API，同时成为 Rust 生态系统中的良好公民。

贡献

如果您对这个项目很感兴趣并想做出贡献，或者如果您发现了任何错误，请随时提出问题或提交拉取请求。我们很高兴看到您的参与！

许可证

MIT 许可证，与 Flecs 相匹配。

示例代码

use flecs_ecs::prelude::*;

#[derive(Debug, Component)]
pub struct Position {
    pub x: f32,
    pub y: f32,
}

#[derive(Debug, Component)]
pub struct Velocity {
    pub x: f32,
    pub y: f32,
}

#[derive(Component)]
pub struct Eats;

#[derive(Component)]
pub struct Apples;

fn main() {
    // Create a new world
    let world = World::new();

    // Register system
    world
        .system::<(&mut Position, &Velocity)>()
        .each(|(pos, vel)| {
            pos.x += vel.x;
            pos.y += vel.y;
        });

    // Create an entity with name Bob, add Position and food preference
    let bob = world
        .entity_named("Bob")
        .set(Position { x: 0.0, y: 0.0 })
        .set(Velocity { x: 1.0, y: 2.0 })
        .add::<(Eats, Apples)>();

    // Show us what you got
    println!("{}'s got [{:?}]", bob.name(), bob.archetype());

    // Run systems twice. Usually this function is called once per frame
    world.progress();
    world.progress();

    bob.get::<&Position>(|pos| {
        // See if Bob has moved (he has)
        println!("{}'s position: {:?}", bob.name(), pos);
    });

    // Output:
    //  Bob's got [Position, Velocity, (Identifier,Name), (Eats,Apples)]
    //  Bob's position: Position { x: 2.0, y: 4.0 }
}

常见问题解答

接下来是什么？

• 元、Json、脚本插件。这将允许创建实体和组件的反射、序列化和脚本功能。更多信息请参阅 Flecs 文档。
• Wasm 未知未知。项目目前正在支持 wasm32-unknown-unknown 目标。预计将在八月底以某种形式落地。
• API 优化，解决安全问题及文档。
• C# 脚本支持。与 Flecs.Net 集成，以无缝与 Flecs Rust API 一起工作。
• 更多演示和示例。

它与其他 Rust ECS 库相比如何？

Flecs 不是用 Rust 本地编写的，而是用 C 编写的，但它是一个成熟且功能丰富的 ECS 库，已用于 AAA 游戏和其他商业软件。它速度快，轻量级，具有许多其他 ECS 库没有的功能。

使 Flecs 独具特色的特性包括

• 一切都是实体。系统、查询和组件都是实体。
• 注重构建器 API 和 DSL 宏，而不是类型系统
  • [构建器 API]

  world.system::<&A>()
  .with::<B>()
  .each(|| { });
  

  • [DSL API]

  system!(world, &A, B)
  .each(|| { });
  

• 单例（资源）被建模为添加到其自身实体的组件。

  world.set(GameTime { delta_time: 0.0 });
  

  • [构建器 API]

  world.system::<&GameTime>()
  .term_at(0)
  .singleton()
  .each(|| { });
  

  • [DSL API]

  system!(world, &R($))
  .each(|| { });
  

• 系统/观察者基于查询，只有在查询匹配时才会运行。
• 系统默认为单线程，并按声明顺序运行（有关 flecs 中的并行性和管道的更多信息，请参阅文档）
• 支持构建自己的自定义管道。
• 关系是 Flecs 中的第一公民，允许轻松创建层次结构。
  • 联合关系、排他关系、oneof 约束、关系遍历、自反关系
• 组件继承
• 传递性
• 查询变量
• 可切换组件
• 实体禁用
• 内置层次结构，自动清理
• 预制件、预制件继承、预制件槽位、预制件层次结构
• flecs 脚本 & flecs 脚本模板
• （分层）实体名称
• 构型级更改检测
• 查询排序
• 查询分组
• 支持注销：组件、模块（插件）、系统、观察者
• 事件传播，事件转发
• 运行时组件
• 使用语言无关的反射框架进行运行时反射
• 语言无关的核心
• 等

使用 Flecs Rust API 的项目

此列表包含不在 NDA 下的项目。

如果您想展示您的项目，请随时提出 PR 以将其添加到列表中。

• [Hyperion]：它已从使用 Envio ECS 切换到 Flecs，性能有了显著提升。它的目标是要打破 10000 名玩家参加的 Minecraft 事件的世界记录。

致谢

向 Sander Mertens 表示衷心的感谢，他创建了这样一个出色的库，并感谢为 Flecs Rust API 做出贡献的预alpha测试者，特别是 James、Bruce 和 Andrew。