diff --git a/docs/assets/application-composition.svg b/docs/assets/application-composition.svg new file mode 100644 index 000000000..6ff1cac44 --- /dev/null +++ b/docs/assets/application-composition.svg @@ -0,0 +1,12 @@ + + Composition within one process + An application manifest selects plugins. The manager installs modules; business modules call registered service interfaces. Application updates and arknet IO workers have separate responsibilities. + + + + Composition within one process + Application processApplication manifestPlugin names and pathsplugin_managerLifecycle and update()Utility plugintimer_moduleguid_moduleBusiness pluginsample1_modulefind_module(): direct interface callsarknet IO workersSeparate from application updates + diff --git a/docs/assets/application-composition_CN.svg b/docs/assets/application-composition_CN.svg new file mode 100644 index 000000000..54e693efc --- /dev/null +++ b/docs/assets/application-composition_CN.svg @@ -0,0 +1,12 @@ + + 进程内的应用组合 + 应用清单交给插件管理器加载插件和模块。业务模块通过接口调用服务，更新循环与 arknet IO 工作线程职责不同。 + + + + 进程内的应用组合 + 应用进程应用清单插件名称与配置路径plugin_manager生命周期与 update()Utility 插件timer_moduleguid_module业务插件sample1_modulefind_module()：获取接口后直接调用arknet IO 工作线程与应用更新线程职责分离 + diff --git a/docs/assets/draft-data-model.svg b/docs/assets/draft-data-model.svg new file mode 100644 index 000000000..7e0530414 --- /dev/null +++ b/docs/assets/draft-data-model.svg @@ -0,0 +1,12 @@ + + Historical data-model sketch + The draft separates entity and configuration metadata at class and field level. A proposed value refers to metadata and a parent relation, with scalar and nested forms. Ownership and migration are open; this is not a current runtime API. + + + + Historical data-model sketch + Draft concept, not a runtime APIEntity metadataClass and field definitionsTypes, masks and hooksConfiguration metadataClass and field definitionsTypes and referencesProposed valueMetadata + parent relationScalar formsBoolean / enumNumbers / stringsNested formsStructure / array / tableOwnership, validation and migration remain open + diff --git a/docs/assets/draft-data-model_CN.svg b/docs/assets/draft-data-model_CN.svg new file mode 100644 index 000000000..07b7d4a48 --- /dev/null +++ b/docs/assets/draft-data-model_CN.svg @@ -0,0 +1,12 @@ + + 历史数据模型草图 + 草案将实体与配置的类级和字段级元数据分开，通用值引用元数据和父级关系，并探索基础值、结构、数组和表格。所有权与迁移规则尚未确定，这不是当前运行时 API。 + + + + 历史数据模型草图 + 设计草案，不是运行时 API实体元数据类与字段定义类型、标记与行为挂钩配置元数据类与字段定义类型与引用通用值的设想元数据 + 父级关系基础值Boolean / 枚举数值 / 字符串嵌套值结构 / 数组 / 表格所有权、验证与迁移规则需要另行设计 + diff --git a/docs/assets/entity-data-flow.svg b/docs/assets/entity-data-flow.svg new file mode 100644 index 000000000..fe9b86de7 --- /dev/null +++ b/docs/assets/entity-data-flow.svg @@ -0,0 +1,12 @@ + + From definitions to runtime data + Metadata loads during init and static records during post_init. Entity creation combines defaults with explicit arguments, then dispatches events in the calling path. Persistence and replication are application policy. + + + + From definitions to runtime data + Schema XML → class_meta_moduleinit(): fields, types, indices and masksValue XML → config_modulepost_init(): static configuration recordskernel_module::create_entity()Schema + optional defaults + explicit argsEntity events → business handlersSynchronous in the calling pathPersistence and replication: application policy + diff --git a/docs/assets/entity-data-flow_CN.svg b/docs/assets/entity-data-flow_CN.svg new file mode 100644 index 000000000..48238d186 --- /dev/null +++ b/docs/assets/entity-data-flow_CN.svg @@ -0,0 +1,12 @@ + + 从定义到运行时数据 + 元数据在 init 阶段加载，静态配置在 post_init 加载，创建实体时将默认值与显式参数合并，再在当前调用路径分发事件。持久化与网络同步由应用决定。 + + + + 从定义到运行时数据 + 定义 XML → class_meta_moduleinit()：字段、类型、索引与标记值 XML → config_modulepost_init()：静态配置记录kernel_module::create_entity()定义 + 可选默认值 + 显式参数实体事件 → 业务回调在当前调用路径同步执行持久化与网络同步：应用策略 + diff --git a/docs/assets/entity-data-model.svg b/docs/assets/entity-data-model.svg new file mode 100644 index 000000000..9fe12bd63 --- /dev/null +++ b/docs/assets/entity-data-model.svg @@ -0,0 +1,12 @@ + + Entity data and definitions + Shared class metadata describes an entity. Runtime entities contain typed nodes, tables and containers; tables contain rows, while containers hold child entities with their own IDs. + + + + Entity data and definitions + class_metaShared definitionsentityOwn ID and runtime statenodeTyped valuetableRows / columnscontainerChildrenrowColumn nodesentityChild IDShared definitions; separate runtime values + diff --git a/docs/assets/entity-data-model_CN.svg b/docs/assets/entity-data-model_CN.svg new file mode 100644 index 000000000..82c4d9cac --- /dev/null +++ b/docs/assets/entity-data-model_CN.svg @@ -0,0 +1,12 @@ + + 实体数据与定义 + 共享的类元数据描述实体结构。运行时实体包含类型化节点、表格与容器；表格持有行，容器持有有独立 ID 的子实体。 + + + + 实体数据与定义 + class_meta共享字段、表格与容器定义entity独立 ID 与运行时状态node类型化的值table行列结构container子实体关系row各列的节点entity子实体 ID共享定义，运行时值分别管理 + diff --git a/docs/assets/server-topology.svg b/docs/assets/server-topology.svg new file mode 100644 index 000000000..417619347 --- /dev/null +++ b/docs/assets/server-topology.svg @@ -0,0 +1,12 @@ + + Reference process topology + Reference roles for entry, cluster services, routing, zones and storage. Dashed connections are application choices, not a claim of implemented discovery, replication or high availability. + + + + Reference process topology + Role reference, not an HA deploymentEntry / directoryEndpoint selectionCluster servicesMaster / shared logicStorage servicesIndependent data policyRouterMessage forwardingZone AWorld / GameProxy / LoginZone BWorld / GameProxy / LoginApplications choose connections and recovery + diff --git a/docs/assets/server-topology_CN.svg b/docs/assets/server-topology_CN.svg new file mode 100644 index 000000000..9bf945af7 --- /dev/null +++ b/docs/assets/server-topology_CN.svg @@ -0,0 +1,12 @@ + + 参考进程拓扑 + 仅说明入口、集群共享服务、路由、区服和存储的职责。虚线为应用选择的连接关系，不声明已具备发现、复制或高可用。 + + + + 参考进程拓扑 + 职责参考，不是已完成的高可用部署入口 / 目录端点选择集群共享服务Master / shared logic存储服务独立的数据策略路由进程目标标识与消息转发区服 AWorld / GameProxy / Login区服 BWorld / GameProxy / Login连接、发现与恢复策略由应用确定 + diff --git a/docs/concepts/application-architecture.md b/docs/concepts/application-architecture.md index c2bef3923..da14ba200 100644 --- a/docs/concepts/application-architecture.md +++ b/docs/concepts/application-architecture.md @@ -1,7 +1,55 @@ # Application architecture -An application consists of plugins, and each plugin contains modules. Modules call other modules through interfaces. This keeps business responsibilities separate and lets an application select its plugin composition. +An ark application is a process assembled from selected plugin libraries. A plugin can register several modules, and modules call each other through registered interfaces. Composition happens within the process; communication with another process uses the [Bus and network interfaces](../reference/bus.md). -![Application composition](../assets/app-architecture.png) +![Application composition and call boundaries](../assets/application-composition.svg) -Kernel manages Entity data. The [Kernel guide](../reference/kernel.md) explains data and events. The [framework architecture](architecture.md) describes application, plugin and module responsibilities. +## From manifest to modules + +The launcher receives `--busid`, `--name` and `--app_conf`. The application manifest chooses shared-library names and optional per-plugin configuration filenames. The shipped `build/conf/sample1.app.conf` is: + +```xml + + + + + + +``` + +New application manifests can use TOML; the equivalent [sample1.app.toml](https://github.com/OpenArkStudio/ark/blob/main/build/conf/sample1.app.toml) is also supplied. A lowercase `.toml` suffix selects TOML, while the legacy `*.app.conf` entry selects XML. See [Application manifests](../service-manifests.md) for the full schema and validation rules; per-plugin and business-resource formats are unchanged. + +The loader loads each library and calls its exported plugin entry. `sample1_plugin::install()` registers `sample1_module`; the utility plugin provides services such as timers. A module resolves those services with `find_module()`, rather than creating another copy of the utility plugin. + +The manifest's names are runtime library names. Existing `AFUtilityPlugin` / `Sample1Plugin` names do not follow the C++ class spelling and must match the built artifacts. Debug libraries use the configured `_d` postfix. An empty `conf` supplies no configuration filename; the loader itself does not parse plugin-specific content. + +## Paths and a runnable starting point + +The existing launcher resolves these paths from its working directory. Library and plugin-configuration prefixes are concatenated with filenames, so retain the trailing separator in `bin/` and `conf/`. The manifest's location does not automatically become the base directory. + +After following [installation](../get-started/installation.md) and preparing the runtime directory, run from `build/`: + +```sh +./bin/app --busid=1.0.1.1 --name=sample1 --app_conf=conf/sample1.app.conf +``` + +The example's `init()` obtains timer and Guid modules; `post_init()` schedules a timer. Its update and shutdown methods demonstrate the module lifecycle. See [sample1_module.cpp](https://github.com/OpenArkStudio/ark/blob/main/examples/sample1/sample1_module.cpp) and the [quick start](../get-started/quick-start.md) for the runtime setup. + +## Choosing the composition + +| Application need | Include and initialize | +| --- | --- | +| Local timers or identifiers | Utility plugin and the corresponding module interfaces | +| Schema-backed entities | Kernel and its dependencies, metadata/configuration resources, maps and instances | +| Process messages | Bus/network plugins, process identity and endpoint configuration | +| Application behavior | An application-owned plugin that registers its business modules | + +Adding a public header or CMake API target only makes an interface available to compile. Runtime configuration still has to load its owning plugin. Modules do not run in a separate process merely because they are in separate libraries. + +## Ordering and ownership + +The manager installs plugins before running the module initialization stages. It does not topologically sort module dependencies or make manifest list order a lifecycle-order contract. Missing-module lookups can return null, and module callback return values are not currently aggregated into a transactional startup result. Verify required plugins/resources and application logs; a running process alone does not prove every service initialized successfully. + +Pointers returned by `find_module()` belong to the loaded plugin. Stop asynchronous producers before teardown and do not retain those pointers after unload. Keeping connections and state through an in-flight business-plugin replacement is not an automatic consequence of this composition model. + +Continue with [framework boundaries](architecture.md), [module implementation](../guides/modules.md), or [Kernel data](../reference/kernel.md). diff --git a/docs/concepts/application-architecture_CN.md b/docs/concepts/application-architecture_CN.md index fcf65ead8..6057773da 100644 --- a/docs/concepts/application-architecture_CN.md +++ b/docs/concepts/application-architecture_CN.md @@ -1,11 +1,55 @@ -# 应用架构介绍 +# 应用架构 -ARK中一个应用(application)是由插件(plugin)组成的, 插件(plugin)由很多模块(module)组成的, module通过面向接口编程(IOP)来做到功能调用. +ark 应用是由选定插件库组成的进程。一个插件可以注册多个模块，模块通过已注册的接口互相调用。这种组合发生在进程内；跨进程通信使用 [Bus 与网络接口](../reference/bus_CN.md)。 -这样做的好处有很多, 解耦、热插拔、模块独立、开发者关注更少、单一原则等等。 +![应用组合与调用边界](../assets/application-composition_CN.svg) -下图是ARk中应用的组成示例: +## 从清单到模块 -![app-architecture](../assets/app-architecture.png) +启动器接收 `--busid`、`--name` 与 `--app_conf`。应用清单选择动态库名称，以及可选的插件配置文件名。仓库提供的 `build/conf/sample1.app.conf` 为： -其中不同插件提供不同的功能, KernelPlugin主要来管理和驱动Entity实例的数据, 详情见[KernelPlugin介绍](../reference/kernel_CN.md). +```xml + + + + + + +``` + +新的应用清单可以使用 TOML，仓库也提供等价的 [sample1.app.toml](https://github.com/OpenArkStudio/ark/blob/main/build/conf/sample1.app.toml)。小写 `.toml` 后缀选择 TOML，原有 `*.app.conf` 入口使用 XML。完整字段与校验规则见[应用清单](../service-manifests_CN.md)；插件专属配置和业务资源格式保持不变。 + +加载器依次加载库并调用导出的插件入口。`sample1_plugin::install()` 注册 `sample1_module`，Utility 插件提供定时器等服务。模块通过 `find_module()` 获取这些服务，不需要再创建一份 Utility 插件。 + +清单名称是运行时库名。现有 `AFUtilityPlugin`、`Sample1Plugin` 不等同于 C++ 类名拼写，必须与构建产物匹配。Debug 库使用配置的 `_d` 后缀。空 `conf` 不提供配置文件名，加载器本身不解析插件专属内容。 + +## 路径与运行入口 + +现有启动器从工作目录解析这些路径。库目录、插件配置目录前缀与文件名直接拼接，因此 `bin/`、`conf/` 需要保留末尾分隔符。清单所在目录不会自动成为相对路径基准。 + +按照[安装说明](../get-started/installation_CN.md)构建并准备运行目录后，在 `build/` 中执行： + +```sh +./bin/app --busid=1.0.1.1 --name=sample1 --app_conf=conf/sample1.app.conf +``` + +示例在 `init()` 获取定时器和 Guid 模块，在 `post_init()` 注册定时器。更新与关闭方法展示模块生命周期。实现见 [sample1_module.cpp](https://github.com/OpenArkStudio/ark/blob/main/examples/sample1/sample1_module.cpp)，运行目录准备见[快速开始](../get-started/quick-start_CN.md)。 + +## 选择插件组合 + +| 应用需求 | 需要加载并初始化 | +| --- | --- | +| 本地定时器或标识生成 | Utility 插件及相应模块接口 | +| 带元数据的实体 | Kernel 及其依赖、元数据与配置资源、地图及实例 | +| 进程消息 | Bus、网络插件，进程标识与端点配置 | +| 应用行为 | 在应用仓库中提供业务模块的插件 | + +包含公开头文件或依赖 CMake API 目标，只让编译器能使用接口；运行时仍需加载所属插件。模块不会因为分别位于不同动态库中，就自动运行在不同进程。 + +## 顺序与所有权 + +管理器先安装插件，再执行模块初始化阶段。它不按依赖关系排序模块，清单中的插件顺序也不是生命周期顺序保证。查找缺失模块可能返回空指针，模块回调返回值目前没有汇总为可回滚的启动结果。需要核对必需插件、资源和应用日志；进程仍在运行，不代表每个服务都已初始化成功。 + +`find_module()` 返回的指针属于已加载插件。释放前先停止异步生产者，插件卸载后不再保留这些指针。在业务函数执行期间替换插件，同时保留连接和状态，需要另外的协调机制，不是这种组合方式自动提供的能力。 + +继续阅读[框架边界](architecture_CN.md)、[模块实现](../guides/modules_CN.md)或 [Kernel 数据](../reference/kernel_CN.md)。 diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md index dcff108c6..c381f8b56 100644 --- a/docs/concepts/architecture.md +++ b/docs/concepts/architecture.md @@ -1,14 +1,53 @@ # Applications, plugins and modules -| Layer | Responsibility | Source entry | +ark composes one application process from plugin libraries. Each plugin registers modules; modules expose interfaces and receive lifecycle calls from `plugin_manager`. Use this page to place responsibilities before following the [application example](application-architecture.md). + +## Responsibility boundaries + +| Component | Owns | Does not provide automatically | | --- | --- | --- | -| Application | Select plugins and process configuration | [Application sources](https://github.com/OpenArkStudio/ark/tree/main/src/app) | -| Plugin | Install and uninstall a group of modules | [ark::sample1_plugin](https://github.com/OpenArkStudio/ark/blob/main/examples/sample1/sample1_plugin.cpp) | -| Module | Provide an interface and participate in the application lifecycle | [ark::module](https://github.com/OpenArkStudio/ark/blob/main/include/ark/module.hpp) | -| Networking | Integrate arknet endpoints and queue application messages/events | [Network plugin](https://github.com/OpenArkStudio/ark/tree/main/src/plugins/net) | +| Application launcher | Process identity, manifest path, plugin selection and the update loop | A cluster scheduler or dependency resolver | +| Plugin | Installation and removal of a group of modules | Safe replacement of code while callbacks still execute | +| Module | A focused interface, its state and lifecycle work | Concurrent access safety for arbitrary business state | +| Kernel plugin | Metadata, static configuration, runtime entities and their events | Automatic persistence or client synchronization merely from declaring a field | +| Network plugin | ark message headers, session identifiers and delivery to the application update thread | Transport algorithms or a separate thread per connection | +| arknet | IO contexts, worker execution and transport operations | Ownership of ark's business entities or application lifecycle | + +[Application composition](application-architecture.md), [data-driven design](data-driven.md) and [reference server topology](server-architecture.md) describe these boundaries at different scales. The server topology is a deployment reference, not a prerequisite for using modules. + +## Calls within a process + +A plugin's `install()` calls `ARK_REGISTER_MODULE(interface_type, implementation_type)`. The manager records that interface, and application code obtains it through typed lookup: + +```cpp +#include "ark/plugin_manager.hpp" +#include "ark/utility/timer_module.hpp" + +ark::timer_module* find_timers(ark::plugin_manager& manager) { + return manager.find_module(); +} +``` + +The returned pointer is borrowed; keep the owning plugin loaded while using it. A missing module triggers an assertion when assertions are enabled, and returns null when they are disabled, so typed lookup is for a required, registered dependency rather than optional-service probing. A header include or CMake dependency does not install a runtime module. See [create a module](../guides/modules.md) and [create a plugin](../guides/plugins.md). + +## Lifecycle and execution + +Startup runs `init()` for modules, then `post_init()`, `check_config()` and `pre_update()`. The launcher repeatedly calls the manager's `update()`; only registered update modules participate in that loop. Shutdown runs `pre_shut()`, then `shut()`, before unloading plugin libraries. + +Use `init()` to obtain dependencies and initialize local resources; use later stages for work that requires other modules' initialization. Stop timers, subscriptions and asynchronous producers before releasing the state their callbacks reference. Network business delivery is advanced through the application's update calls; network IO still runs on arknet workers. + +Current limits matter when composing modules: + +- Modules are traversed through manager containers, without a declared dependency graph or guaranteed manifest order. Do not depend on one module being initialized first within the same stage. +- The current manager invokes lifecycle callbacks without aggregating their Boolean results. Returning `false` from a module is not a general guarantee of transactional startup rollback or process termination. +- Lifecycle stages do not establish that arbitrary business tasks have drained. Compatible hot replacement and plugin-unload coordination remain separate design work. + +The source of these rules is [plugin_manager.hpp](https://github.com/OpenArkStudio/ark/blob/main/include/ark/plugin_manager.hpp) and the [launcher](https://github.com/OpenArkStudio/ark/blob/main/src/app/main.cpp). + +## Header paths and CMake targets -The module interface offers `init`, `post_init`, `check_config`, `pre_update`, `update`, `pre_shut` and `shut`. Keep initialization and shutdown responsibilities paired. Stop callback sources before releasing modules they reference. +All public headers live under `include/ark/`; for example, `include/ark/kernel/entity.hpp` is included as ``. Core target definitions live in `src/core/` and plugin implementations in `src/plugins//`. `ark::core` supplies core headers; the individual plugin targets remain optional, and `ark::ark` aggregates available API targets. -arknet provides IO contexts, threads and transport operations. ark's network plugin handles application message headers, session IDs and Update-thread delivery. Protocol algorithms and IO thread runners belong in arknet. +`ark/` is a filesystem include prefix. It does not automatically create the C++ namespace: each header explicitly declares `namespace ark`. Linking an API interface target propagates compilation requirements; it does not select or load a plugin shared library. -Continue with [plugin creation](../guides/plugins.md) or [networking](../networking.md). +Implementation headers still share some `include/` directories with public interfaces. Treat `*_impl` types as implementation details, and do not interpret the current paths as a completed public/private separation. The diagrams describe responsibilities rather than prescribing a physical directory layout. See [directory structure](../reference/directory-structure.md) for the current paths and targets. diff --git a/docs/concepts/architecture_CN.md b/docs/concepts/architecture_CN.md index 5be6ad387..b460f717a 100644 --- a/docs/concepts/architecture_CN.md +++ b/docs/concepts/architecture_CN.md @@ -1,14 +1,53 @@ # 应用、插件与模块 -| 层级 | 职责 | 源码入口 | +ark 在一个应用进程中组合多个插件库。插件注册模块，模块提供接口，并接受 `plugin_manager` 的生命周期调用。先确定各层职责，再阅读[应用组合示例](application-architecture_CN.md)。 + +## 职责边界 + +| 组件 | 负责 | 不会自动提供 | | --- | --- | --- | -| 应用 | 选择插件与进程配置 | [应用源码](https://github.com/OpenArkStudio/ark/tree/main/src/app) | -| 插件 | 安装与卸载一组模块 | [ark::sample1_plugin](https://github.com/OpenArkStudio/ark/blob/main/examples/sample1/sample1_plugin.cpp) | -| 模块 | 提供接口，参与应用生命周期 | [ark::module](https://github.com/OpenArkStudio/ark/blob/main/include/ark/module.hpp) | -| 网络 | 使用 arknet 端点，排队分发业务消息与事件 | [网络插件](https://github.com/OpenArkStudio/ark/tree/main/src/plugins/net) | +| 应用启动器 | 进程标识、清单路径、插件选择与更新循环 | 集群调度或依赖解析 | +| 插件 | 一组模块的安装与移除 | 回调仍在执行时的安全代码替换 | +| 模块 | 专项接口、状态与生命周期工作 | 任意业务状态的并发访问安全 | +| Kernel 插件 | 元数据、静态配置、运行时实体及其事件 | 仅声明字段就自动持久化或同步到客户端 | +| 网络插件 | ark 消息头、会话标识，以及向应用更新线程交付消息 | 传输算法或每连接独立线程 | +| arknet | IO context、工作线程执行与传输操作 | ark 业务实体或应用生命周期的管理 | + +[应用组合](application-architecture_CN.md)、[数据驱动](data-driven_CN.md)和[参考服务拓扑](server-architecture_CN.md)分别说明不同层次的关系。服务拓扑是部署参考，使用模块并不要求先部署整套服务。 + +## 进程内调用 + +插件在 `install()` 中调用 `ARK_REGISTER_MODULE(interface_type, implementation_type)`。管理器记录该接口，应用通过类型查找模块： + +```cpp +#include "ark/plugin_manager.hpp" +#include "ark/utility/timer_module.hpp" + +ark::timer_module* find_timers(ark::plugin_manager& manager) { + return manager.find_module(); +} +``` + +返回值是借用指针，使用期间应保持所属插件已加载。模块缺失时，启用断言的构建会触发断言，关闭断言后才返回空指针；因此类型查找用于获取已注册的必需依赖，不适合探测可选服务。包含头文件或添加 CMake 依赖不会在运行时安装模块。详见[创建模块](../guides/modules_CN.md)与[创建插件](../guides/plugins_CN.md)。 + +## 生命周期与执行 + +启动时依次执行所有模块的 `init()`、`post_init()`、`check_config()` 和 `pre_update()` 阶段。启动器持续调用管理器的 `update()`，其中只有已注册更新的模块参与循环。停止时先调用 `pre_shut()`，再调用 `shut()`，然后卸载插件库。 + +在 `init()` 中获取依赖并初始化本地资源；需要其他模块完成初始化的工作放在后续阶段。释放回调引用的状态前，先停止定时器、订阅与异步生产者。网络业务消息通过应用更新调用推进，网络 IO 仍由 arknet 工作线程执行。 + +组合模块时需要遵守当前限制： + +- 管理器按容器遍历模块，没有声明式依赖图，也不保证清单顺序。同一阶段内不能依赖某个模块先初始化。 +- 当前管理器调用生命周期回调时没有汇总各模块的 Boolean 返回值。模块返回 `false` 不等于框架保证回滚整个启动过程或终止进程。 +- 生命周期阶段不代表任意业务任务已经排空。兼容热替换与插件卸载协调仍是独立设计事项。 + +对应实现见 [plugin_manager.hpp](https://github.com/OpenArkStudio/ark/blob/main/include/ark/plugin_manager.hpp) 和[启动器](https://github.com/OpenArkStudio/ark/blob/main/src/app/main.cpp)。 + +## 头文件路径与 CMake 目标 -模块接口提供 `init`、`post_init`、`check_config`、`pre_update`、`update`、`pre_shut` 和 `shut`。初始化与关闭职责应成对处理；释放模块前，先停止引用它的回调来源。 +所有公开头文件统一位于 `include/ark/`，例如 `include/ark/kernel/entity.hpp` 对应 ``。核心目标定义位于 `src/core/`，插件实现位于 `src/plugins//`。`ark::core` 提供核心头文件，各插件仍保留独立可选目标，`ark::ark` 汇总可用 API 目标。 -arknet 提供 IO context、线程和传输操作。ark 网络插件负责业务消息头、Session ID 与 Update 线程上的消息分发。协议算法和 IO 线程执行逻辑放在 arknet 中。 +`ark/` 是文件系统中的头文件前缀，不会自动创建 C++ 命名空间；命名空间由各头文件显式声明的 `namespace ark` 决定。依赖 API 接口目标只传递编译要求，不会选择或加载插件动态库。 -继续阅读[创建插件](../guides/plugins_CN.md)或[网络与测试](../networking_CN.md)。 +部分实现头文件仍与公开接口混放在 `include/` 目录中。将 `*_impl` 类型视为实现细节，不能把当前路径理解为已完成公开接口与实现的隔离。图示按职责组织，不限定物理目录布局。当前路径与目标见[目录结构](../reference/directory-structure_CN.md)。 diff --git a/docs/concepts/data-driven.md b/docs/concepts/data-driven.md index f380485a4..5ec0cdc2c 100644 --- a/docs/concepts/data-driven.md +++ b/docs/concepts/data-driven.md @@ -1,7 +1,56 @@ # Data-driven design -ark separates metadata, configuration and runtime Entity values. Metadata describes fields and tables; configuration supplies values; modules respond to Entity and data events. +ark separates a class's schema, reusable configuration records and mutable runtime entities. Business modules use the Kernel interfaces to read or change that data and react to events. Changing a schema does not itself generate business rules, database writes or network replication. -![Data-driven event flow](../assets/data-node-sample.png) +![Metadata, configuration and runtime event flow](../assets/entity-data-flow.svg) -Read [data structures](../guides/data-structures.md) for Node, Table and Container relationships, and [Kernel](../reference/kernel.md) for event registration and data access. Configuration generation is described under [tools](../guides/tools.md). +## Three different kinds of data + +| Kind | Defines or contains | Owner / access | +| --- | --- | --- | +| Metadata | Field names, indices, types, masks, table-row classes and container-child classes | `class_meta_module`, `class_meta` | +| Static configuration | Named class records indexed by configuration ID | `config_module`, `static_entity` | +| Runtime entity | An entity ID, class, mutable fields, tables and child entities | `kernel_module`, `entity` | + +Metadata describes what values mean. A configuration ID identifies a reusable record, while an entity ID identifies one runtime object. Multiple entities can start from one configuration without sharing mutable node values. See [data structures](../guides/data-structures.md) for the APIs and ownership of each object. + +## Loading resources + +`class_meta_module` loads `resource/meta/config_class.config` and `resource/meta/entity_class.config` during `init()`. These lists reference schema files; configuration metadata can also reference value resources. `config_module` loads static records in `post_init()`, after metadata initialization. + +These are paths under `resource/` in the process working directory. Legacy references beginning with `/` are still treated as resource-relative paths. They are business metadata/configuration XML, separate from the application's plugin manifest. The [configuration tool](../guides/tools.md) generates resources and C++ metadata indices; generated metadata files must be prepared for a real deployment and are not all supplied as tracked runtime output. + +Keep field names, indices, types and generated `meta_define.hpp` consistent. A C++ naming cleanup does not authorize changing externally stored schema names or protocol field numbers. + +## Creating an entity with defaults + +Entity creation requires an existing class schema, map and map instance. A positive configuration ID must refer to a record of the same class. Configuration provides defaults; explicit initialization arguments take precedence for the same field, including zero and empty values. Unspecified fields keep configuration values. + +This example sets `Player.level` to `0`. The caller has already created the map/instance and loaded a matching configuration record: + +```cpp +#include + +#include "ark/kernel/data_list_impl.hpp" +#include "ark/kernel/kernel_module.hpp" +#include "ark/meta_define.hpp" + +std::shared_ptr spawn_player( + ark::kernel_module& kernel, int map_id, int instance_id, ark::id_type config_id) { + ark::data_list_impl args; + args.add_int(0); + args.add_u_int(ark::entity_meta_player::level_index()); + return kernel.create_entity( + ark::null_guid, map_id, instance_id, ark::entity_meta_player::self_name(), config_id, args); +} +``` + +Arguments are `(value, uint32_t field_index)` pairs, with exact schema types. Check the returned pointer before using the entity. Invalid schema/map/configuration, duplicate IDs or malformed arguments can fail creation. See [Kernel creation and defaults](../reference/kernel.md) for full examples and the restore-from-Protobuf distinction. + +## Events and application policy + +Defaults and arguments are established before the first creation event, `entity_evt_pre_load_data`. The ordinary create overload then dispatches its class events synchronously through `entity_evt_data_finished`. Field/table/container events let modules respond to changes; handlers run in the calling execution path, not on an automatically created business-event worker. + +Register handlers before creating the relevant entities, and keep callback owners alive. Callback registration does not currently provide a general public unregister counterpart. Avoid holding pointers across entity/row destruction or modifying shared entity state directly from unrelated IO workers. + +Masks describe persistence/synchronization intent, but declaring `save`, `sync_self` or `sync_view` does not configure a database, select recipients or guarantee delivery. The application still decides when to serialize, persist, synchronize and recover state. The [Kernel reference](../reference/kernel.md) documents callbacks and conversion APIs; [application architecture](application-architecture.md) explains module ownership. diff --git a/docs/concepts/data-driven_CN.md b/docs/concepts/data-driven_CN.md index 8306bfd10..9c756fafb 100644 --- a/docs/concepts/data-driven_CN.md +++ b/docs/concepts/data-driven_CN.md @@ -1,7 +1,56 @@ # 数据驱动 -ark 将元数据、配置与运行时 Entity 的值分开管理。元数据描述字段与表结构，配置提供取值，模块通过 Entity 事件与数据事件组织业务逻辑。 +ark 将类定义、可复用的配置记录和可修改的运行时实体分开管理。业务模块通过 Kernel 接口读取或修改数据，并响应事件。修改元数据本身不会自动生成业务规则、数据库写入或网络复制。 -![数据驱动示例](../assets/data-node-sample.png) +![元数据、配置与运行时事件流程](../assets/entity-data-flow_CN.svg) -[数据结构](../guides/data-structures_CN.md)介绍 Node、Table 和 Container 的关系，[Kernel](../reference/kernel_CN.md)介绍事件注册与数据访问。配置生成流程见[配置工具](../guides/tools_CN.md)。 +## 三类数据 + +| 类型 | 定义或包含 | 管理与访问 | +| --- | --- | --- | +| 元数据 | 字段名、索引、类型、标记、表行类型与容器子实体类型 | `class_meta_module`、`class_meta` | +| 静态配置 | 按配置 ID 索引的类记录 | `config_module`、`static_entity` | +| 运行时实体 | 实体 ID、类、可变字段、表格与子实体 | `kernel_module`、`entity` | + +元数据说明值的含义。配置 ID 标识可复用记录，实体 ID 标识一个运行时对象。多个实体可以从同一配置初始化，而不共享可变节点值。各对象的 API 与所有权见[数据结构](../guides/data-structures_CN.md)。 + +## 加载资源 + +`class_meta_module` 在 `init()` 加载 `resource/meta/config_class.config` 和 `resource/meta/entity_class.config`。这些清单引用各个定义文件，配置元数据还可以引用值资源。`config_module` 在元数据初始化之后的 `post_init()` 加载静态记录。 + +路径位于进程工作目录下的 `resource/` 中。旧引用即使以 `/` 开头，也按资源相对路径处理。这些文件是业务元数据与配置 XML，独立于选择插件的应用清单。[配置工具](../guides/tools_CN.md)生成资源及 C++ 元数据索引；真实部署需要准备生成文件，仓库没有跟踪全部运行时生成产物。 + +字段名、索引、类型与生成的 `meta_define.hpp` 必须保持一致。统一 C++ 命名，不代表可以改变外部存储中的定义名称或协议字段编号。 + +## 使用配置默认值创建实体 + +创建实体前需要存在类定义、地图与地图实例。正数配置 ID 必须指向同类记录。配置提供默认值，显式初始化参数覆盖同名字段，包括零值与空值；未指定字段保留配置值。 + +下例将 `Player.level` 设为 `0`。调用前已经创建地图与实例，并加载匹配的配置记录： + +```cpp +#include + +#include "ark/kernel/data_list_impl.hpp" +#include "ark/kernel/kernel_module.hpp" +#include "ark/meta_define.hpp" + +std::shared_ptr spawn_player( + ark::kernel_module& kernel, int map_id, int instance_id, ark::id_type config_id) { + ark::data_list_impl args; + args.add_int(0); + args.add_u_int(ark::entity_meta_player::level_index()); + return kernel.create_entity( + ark::null_guid, map_id, instance_id, ark::entity_meta_player::self_name(), config_id, args); +} +``` + +参数为 `(value, uint32_t field_index)` 配对，类型必须与定义完全一致。使用实体前检查返回指针。缺失定义、地图或配置、重复 ID，以及错误参数都可能导致创建失败。完整示例及 Protobuf 恢复路径的区别见 [Kernel 创建与默认值](../reference/kernel_CN.md)。 + +## 事件与应用策略 + +默认值和参数在首个创建事件 `entity_evt_pre_load_data` 前准备完成。普通创建重载随后同步分发类事件，直到 `entity_evt_data_finished`。字段、表格与容器事件让模块响应变化，回调在当前调用路径中执行，不会自动创建业务事件线程。 + +在创建相关实体前注册回调，并保持回调所属对象存活。当前回调注册接口没有通用的公开注销方法。实体或行销毁后不再使用原指针，也不要从无关 IO 工作线程直接修改共享实体状态。 + +标记描述持久化或同步意图，但声明 `save`、`sync_self`、`sync_view` 不会自动配置数据库、选择接收者或保证交付。何时序列化、持久化、同步与恢复，仍由应用决定。[Kernel 参考](../reference/kernel_CN.md)说明回调与数据转换 API，[应用架构](application-architecture_CN.md)说明模块所有权。 diff --git a/docs/concepts/server-architecture.md b/docs/concepts/server-architecture.md index c56d1ea1f..a2fa2dab0 100644 --- a/docs/concepts/server-architecture.md +++ b/docs/concepts/server-architecture.md @@ -1,13 +1,36 @@ # Server architecture -This reference topology separates directory/discovery, cluster-wide services, routers, zones and storage. It illustrates process roles rather than a measured production capacity. +ark can assemble different server processes from the same plugin/module interfaces. The topology below is a reference for assigning responsibilities in a multi-process deployment. It is not a turnkey cluster, an implemented Registry service, or a measured capacity result. -![Reference process topology](../assets/server-architecture.png) +![Reference process roles and deployment boundaries](../assets/server-topology.svg) -- Directory services identify the destination environment. -- Master and shared services operate at cluster scope. -- Routers bridge zones and shared services. -- World, game, proxy and login processes form each zone. -- Storage services have their own scaling and failure domains. +## Separate roles before scaling -The [routing proposal](../project/network-design.md) explains the cluster/router/zone split. Concrete deployment, discovery and recovery policies require application-specific configuration and tests. +| Reference role | Responsibility | Application decisions | +| --- | --- | --- | +| Entry / directory | Direct a client to an environment or entry endpoint | Authentication, endpoint selection and discovery source | +| Cluster services | Coordinate work shared across zones, such as a master or shared business service | Ownership, state recovery and failover | +| Router | Forward selected messages between zone and cluster processes | Destination IDs, allowed routes, congestion handling | +| Zone services | Run a zone's world, game, proxy or login responsibilities | Sharding, player placement and zone boundaries | +| Storage services | Store application records independently from process routing | Data model, replication, durability and backup | + +These roles need not be separate binaries for every application. Begin with the processes required by the workload; introduce a boundary when its ownership, scaling or failure behavior needs to differ. A plugin boundary alone is not a network or high-availability boundary. + +## What the repository supplies + +`src/server/` contains example process roles such as `master`, `router`, `world`, `game`, `proxy`, `login` and `dir`. Their corresponding `build/conf/*.app.conf` manifests select plugins. A role's source directory and configuration demonstrate composition; they do not certify that every service in the reference topology is complete. + +The Bus plugin represents process addresses and routing destinations. Use the [Bus reference](../reference/bus.md) to configure local process relationships, create a connection, and send a message with the required identifiers. The [network plugin](../reference/network.md) supplies transport integration. Module-to-module calls inside a process continue to use direct interfaces, as shown in [application architecture](application-architecture.md). + +## Start from a verified pair + +1. Prepare one application's runtime directory using the [quick start](../get-started/quick-start.md). +2. Give each process its own Bus identity, manifest and endpoints. A shared library filename is not a process identity. +3. Verify a local client/server or Bus connection with a small workload and inspect both sides' logs before adding routing layers. +4. Add multiple zones or routers only with explicit ownership and recovery rules. Keep the target workload and failure tests with the deployment configuration. + +Discovery is a separate integration decision. The framework does not require every deployment to start Consul. Configuration-driven endpoints, platform discovery and an optional integration have different operational requirements; none makes a custom multi-node Registry or automatic failover already available. See the [routing design proposal](../project/network-design.md) for the historical cluster/router/zone concept, not a released HA contract. + +## Limits to verify in a deployment + +Endpoint connectivity alone does not verify authentication, message delivery after reconnect, state transfer, split-brain behavior or storage consistency. The 100,000–200,000 concurrent-user target is a multi-process deployment goal, not a measured single-process limit. [Benchmarks and acceptance](../performance/benchmark.md) distinguish local correctness/performance tools from cross-host capacity and endurance tests. diff --git a/docs/concepts/server-architecture_CN.md b/docs/concepts/server-architecture_CN.md index 0743c7b31..f085506ab 100644 --- a/docs/concepts/server-architecture_CN.md +++ b/docs/concepts/server-architecture_CN.md @@ -1,13 +1,36 @@ # 服务器架构 -参考拓扑将目录与发现、全局服务、路由、小区和存储分开部署。图中展示进程职责，不代表已经测得的生产容量。 +ark 可以使用同一组插件与模块接口组合不同的服务进程。下图用于为多进程部署分配职责，不表示已经提供开箱即用的集群、Registry 服务或实测容量。 -![参考进程拓扑](../assets/server-architecture.png) +![参考进程职责与部署边界](../assets/server-topology_CN.svg) -- 目录服务确定目标环境。 -- Master 与共享服务承担全区职责。 -- Router 连接小区与共享服务。 -- World、Game、Proxy 和 Login 等进程组成小区。 -- 存储服务具有独立的扩容与故障边界。 +## 先划分职责，再扩展规模 -[路由设计提案](../project/network-design_CN.md)说明 cluster、router 和 zone 的划分。具体部署、发现与恢复策略需要结合应用配置和验证。 +| 参考角色 | 职责 | 应用需要决定 | +| --- | --- | --- | +| 入口与目录 | 将客户端引导到环境或入口端点 | 鉴权、端点选择与发现来源 | +| 集群服务 | 协调跨区共享工作，例如 Master 或公共业务服务 | 状态归属、恢复与故障切换 | +| 路由进程 | 在区服与集群进程之间转发指定消息 | 目标标识、允许的路由与拥塞处理 | +| 区服服务 | 承担 World、Game、Proxy、Login 等职责 | 分片、玩家分配与区服边界 | +| 存储服务 | 独立于进程路由保存应用记录 | 数据模型、复制、持久性与备份 | + +并非每个应用都需要为这些角色单独部署进程。先保留负载需要的进程，当状态归属、扩容或故障行为需要分离时，再增加边界。插件边界本身不等于网络边界或高可用边界。 + +## 仓库提供的内容 + +`src/server/` 包含 `master`、`router`、`world`、`game`、`proxy`、`login`、`dir` 等示例角色，`build/conf/*.app.conf` 中的相应清单选择插件。角色目录与配置展示组合方式，不代表参考拓扑中的每种服务都已经完整实现。 + +Bus 插件表示进程地址与路由目标。[Bus 参考](../reference/bus_CN.md)说明如何配置本地进程关系、创建连接，以及携带所需标识发送消息；[网络插件](../reference/network_CN.md)提供传输集成。进程内的模块调用仍使用直接接口，见[应用架构](application-architecture_CN.md)。 + +## 从已验证的进程对开始 + +1. 按[快速开始](../get-started/quick-start_CN.md)准备一个应用的运行目录。 +2. 为每个进程分别设置 Bus 标识、清单与端点。动态库文件名不是进程标识。 +3. 先验证本机客户端与服务端或 Bus 连接，用小负载检查两端日志，再增加路由层。 +4. 增加多个区服或 Router 前，明确状态归属与恢复规则，并将目标负载和故障测试保存在部署配置旁。 + +服务发现是独立的集成选型，框架并不要求每种部署都启动 Consul。配置文件端点、平台发现与可选集成各有运维要求；它们都不表示框架已经提供自研多节点 Registry 或自动故障切换。[路由设计提案](../project/network-design_CN.md)描述历史上的 cluster/router/zone 思路，不是已发布的高可用契约。 + +## 部署时需要验证的边界 + +端点可连通，不等于已经验证鉴权、重连后的消息交付、状态转移、网络分区行为或存储一致性。10 万至 20 万同时在线是多进程部署目标，不是实测的单进程上限。[基准测试与验收](../performance/benchmark_CN.md)区分本机正确性与性能工具，以及跨主机容量和耐久测试。 diff --git a/docs/guides/data-structures.md b/docs/guides/data-structures.md index f16b91587..76c7303b7 100644 --- a/docs/guides/data-structures.md +++ b/docs/guides/data-structures.md @@ -1,185 +1,87 @@ # Data structures and metadata -The separation of definitions and values remains: metadata describes field names, indices, types and flags; entities retain definitions and values. Public types now live in `include/ark/kernel/` with the snake_case names below. See [configuration tools](tools.md) for generated C++ and [Protobuf](../reference/protobuf.md) for protocol messages. +Use a node for one typed value, a table for rows with a shared schema, and a container for child entities. All three belong to the Kernel data model; their definitions are separate from their runtime values. This guide uses the current snake_case interfaces, not the historical AF-prefixed implementation layouts. -| Historical name | Current name | -| --- | --- | -| `AFNodeMeta` | `node_meta` | -| `AFTableMeta` | `table_meta` | -| `AFContainerMeta` | `container_meta` | -| `AFClassMeta` | `class_meta` | -| `AFIStaticEntity / AFCStaticEntity` | `static_entity / static_entity_impl` | -| `AFIEntity / AFCEntity` | `entity / entity_impl` | -| `AFNodeManager` | `node_manager` | -| `AFTableManager` | `table_manager` | -| `AFIContainer / AFCContainer` | `container / container_impl` | -| `AFITable / AFCTable` | `table / table_impl` | -| `AFIRow / AFCRow` | `row / row_impl` | +The public Kernel interfaces live in `include/ark/kernel/`. See [configuration tools](tools.md) for generated C++ and [Protobuf](../reference/protobuf.md) for protocol messages. -The original article's field descriptions, manager relationships and diagram are preserved below. Its AF-prefixed types and member layouts are historical implementation snapshots; use the corresponding public headers for current code instead of depending on those private layouts. +![Entity fields, tables, containers and their metadata](../assets/entity-data-model.svg) -
-Original data-structure design and field reference +## Data definitions -`ARK` separates data values from their definitions. A definition contains the name, index, type and flags such as whether the value is persisted. A data entity holds a pointer to its definition and the value itself. Object properties are stored as a mapping from indices to values. +| Definition | Describes | Runtime value | +| --- | --- | --- | +| `node_meta` | Field name, index, value type and masks | `node`, accessed through `entity` or `row` | +| `table_meta` | Table name/index, row class and masks | `table` with `row` objects | +| `container_meta` | Container name/index, allowed child class and masks | `container` holding child entities | +| `class_meta` | Class name, field-index mapping and the three definition collections | `entity` or configuration `static_entity` | -## Data configuration generation - -The `gen-config` tool in `build/tools` reads files from `build/resource/excel` and generates data definitions in `build/resource/meta` and configuration files in `build/resource/server`. It also generates interfaces for class property names and indices in `build/resource/code`. - -### Data definitions - -There are four data definition classes: - -1. `AFNodeMeta` defines an object property. - -- `name_`: property name, `string` -- `type_`: value type, `enum class ArkDataType` -- `index_`: index, `uint32` -- `mask_`: flags for persistence, synchronization and related features, `std::bitset` - -2. `AFTableMeta` defines a table structure. - -- `name_`: table name, `string` -- `index_`: index, `uint32` -- `type_name_`: name of the table's `AFClassMeta`, `string` -- `class_meta_`: corresponding `AFClassMeta`, `ARK_SHARE_PTR` -- `mask_`: flags for persistence, synchronization and related features, `std::bitset` - -3. `AFContainerMeta` defines a container that holds objects to form more complex data structures. - -- `name_`: container name, `string` -- `index_`: index, `uint32` -- `class_name_`: class name of the objects stored in the container, `string` - -4. `AFClassMeta` defines a class structure. - -- `name_`: class name, `string` -- `res_path_`: resource path, string -- `name_index_list_`: mapping from field names to indices, `map` -- `data_meta_list_`: property map, `map` -- `table_meta_list_`: table map, `map` -- `container_meta_list_`: container map, `map` -- `class_meta_call_back_`: callback function, `pointer` - -### Data entities - -There are two data entity classes: - -1. `AFCStaticEntity` represents configuration data and implements `AFIStaticEntity `. - -- `config_id_`: configuration ID, `int`. It is stored separately because it is widely used and frequently accessed. -- `m_pNodeManager`: property manager, `ARK_SHARE_PTR` +Metadata is shared description, not an entity's mutable state. A table's row class describes its columns. A container holds entities with their own IDs; it is not a table row or an untyped map. Choose the structure according to the operations and ownership the application needs. -2. `AFCEntity ` represents an entity object and implements `AFIEntity `. +## Find metadata before accessing values -- `guid_`: unique identifier, `AFGUID` -- `config_id_`: configuration ID, `int` -- `parent_container_`: pointer to the owning container, `ARK_SHARE_PTR` -- `map_entity_id_`: map entity ID, `int` -- `custom_data_list_`: custom properties, `hashmap`. Properties can be added or removed without defining them in a file first. -- `m_pNodeManager`: property manager, `ARK_SHARE_PTR` -- `m_pTableManager`: table manager, `ARK_SHARE_PTR` -- `m_pContainerManager`: container manager, `ARK_SHARE_PTR` -- `m_pEventManager`: event manager, `ARK_SHARE_PTR` +The metadata module loads schema resources during initialization. Check that the class and field exist and use the accessor matching the declared type: -These entities use the following classes: +```cpp +#include +#include -- `AFNodeManager` manages an object's properties. +#include "ark/kernel/class_meta_module.hpp" - ```cpp - using DataList = AFMap; +bool is_int32_field(ark::class_meta_module& schemas, const std::string& class_name, std::uint32_t index) { + auto schema = schemas.find_meta(class_name); + if (schema == nullptr) + { + return false; + } + auto field = schema->find_data_meta(index); + return field != nullptr && field->get_type() == ark::data_type::dt_int32; +} +``` - // class meta - ARK_SHARE_PTR class_meta_{nullptr}; +`entity::get_node_type()` checks a runtime field's declared type. Then use `get_int32()` / `set_int32()`, `get_string()` / `set_string()` or the corresponding typed accessor. Zero and an empty string are values, not reliable indicators that an entity or field is missing. - // call back - NODE_COMPONENT_FUNCTOR func_; +## Work with tables and rows - // data list - DataList data_list_; - ``` +A table is created from its declared table metadata. The following function finds or adds one row and writes a known int32 column. The caller supplies schema indices; it does not create a schema or infer a column from the value. -- `AFTableManager` manages tables, including creation and lookup. +```cpp +#include - ```cpp - using TableList = AFMap; +#include "ark/kernel/entity.hpp" +#include "ark/kernel/table.hpp" - // class meta - ARK_SHARE_PTR class_meta_{nullptr}; +bool set_row_value(ark::entity& owner, std::uint32_t table_index, + std::uint32_t row_index, std::uint32_t column_index, std::int32_t value) { + auto* table = owner.find_table(table_index); + if (table == nullptr || table->get_col_type(column_index) != ark::data_type::dt_int32) + { + return false; + } + auto* row = table->find_row(row_index); + if (row == nullptr) + { + row = table->add_row(row_index); + } + return row != nullptr && row->set_int32(column_index, value); +} +``` - // table list - TableList table_list_; - ``` +`find_table()`, `find_row()` and `add_row()` return borrowed pointers. Do not retain a row after `remove_row()` or `clear()`, or retain a table after its entity is destroyed. Row IDs and column indices are different identifiers. A nonzero row ID selects a specific row; `add_row(0)` allocates a row ID. Register table callbacks before mutations when the application needs change notifications. -- `AFIContainerManager`, implemented by `AFCContainerManager`, manages containers, including creation and lookup. +## Work with child entities - ```cpp - // container - using ContainerList = AFSmartPtrMap; - ContainerList container_data_; - ``` +`entity::find_container(index)` returns a container object or null. Use `kernel_module::create_container_entity(parent_id, container_index, class_name, config_id)` to create a schema-compatible child. Check its return value; the parent, container definition, class and optional matching configuration must exist. -- `AFIContainer`, implemented by `AFCContainer`, holds child objects to form complex structures. +Use `container::find(slot)` or lookup by child ID to find placement. `place()` and `swap()` change placement; `remove()` and `destroy()` are distinct operations, so choose according to whether the application intends detachment or destruction. A retained `shared_ptr` is not proof that the entity remains registered in Kernel. Re-query its ID when live registration matters. - ```cpp - using EntityDataList = AFSmartPtrMap; +## Configuration and runtime ownership - // contain entity class meta - ARK_SHARE_PTR container_meta_{nullptr}; +`static_entity` is a loaded configuration record. `entity` adds runtime identity, mutable nodes, tables, containers and event behavior. Ordinary entity creation uses configuration as defaults and preserves explicit initialization arguments; later entity writes do not alter the original configuration record. See [data-driven creation](../concepts/data-driven.md). - // index start - uint32_t current_index_{0u}; +`node_manager`, `table_manager` and `container_manager` organize the corresponding runtime collections. Applications normally use the public entity/table/container interfaces instead of depending on manager internals or `*_impl` member layouts. Borrowed pointers and callbacks do not make these objects safe for concurrent mutation from arbitrary threads. - // parent id - AFGUID parent_{NULL_GUID}; - - // entity data - EntityDataList entity_data_list_; - ``` - -- `AFIEventManager` handles an object's events. - -- `AFINode`, implemented by `AFCNodeTypeName` (where `TypeName` is a built-in type name), holds a property value and its definition. - - ```cpp - // meta - ARK_SHARE_PTR data_meta_{nullptr}; - - // value - TypeName data_{TypeName()}; - ``` - -- `AFITable` is the table interface, implemented by `AFCTable`. - - ```cpp - using TableData = AFMap; - - // object unique guid - AFGUID guid_{NULL_GUID}; - - // table meta - ARK_SHARE_PTR table_meta_{nullptr}; - - // current row - uint32_t current_row{0u}; - - // table data - TableData data_; - ``` - -- `AFIRow` is the table row interface, implemented by `AFCRow`. - - ```cpp - // row - uint32_t row_{0u}; - - // data - ARK_SHARE_PTR m_pNodeManager{nullptr}; - ``` - -### Structure diagram +## Data configuration generation -![data structure](../assets/data-structure.png) +The existing [configuration tool](tools.md) generates XML metadata, static values and C++ field-index definitions. Keep them consistent when changing a schema. Field masks such as save/synchronization intent require application code to choose persistence and delivery policy; they are not automatic storage or replication. -
+The [Kernel reference](../reference/kernel.md) provides complete creation, typed access, callbacks and conversion examples. [Application architecture](../concepts/application-architecture.md) explains when the modules are available. Historical AF-prefixed layouts remain in [the original source article](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/en-us/data-structure.md); those private layouts are not the current API contract. diff --git a/docs/guides/data-structures_CN.md b/docs/guides/data-structures_CN.md index b8f23c7e8..62ee7e820 100644 --- a/docs/guides/data-structures_CN.md +++ b/docs/guides/data-structures_CN.md @@ -1,185 +1,87 @@ # 数据结构与元数据 -数据与定义分离的设计仍保留：元数据描述字段名、下标、类型和标志，实体保存引用及其值。当前公开类型位于 `include/ark/kernel/`，使用以下 snake_case 名称。配置工具生成 C++ 的流程见[配置工具](tools_CN.md)，协议消息见 [Protobuf](../reference/protobuf_CN.md)。 +单个类型化的值使用节点，结构相同的行使用表格，需要包含子实体时使用容器。三者都属于 Kernel 数据模型，定义与运行时值分别管理。本页使用当前 snake_case 接口，不依赖历史 AF 前缀的实现布局。 -| 旧名称 | 当前名称 | -| --- | --- | -| `AFNodeMeta` | `node_meta` | -| `AFTableMeta` | `table_meta` | -| `AFContainerMeta` | `container_meta` | -| `AFClassMeta` | `class_meta` | -| `AFIStaticEntity / AFCStaticEntity` | `static_entity / static_entity_impl` | -| `AFIEntity / AFCEntity` | `entity / entity_impl` | -| `AFNodeManager` | `node_manager` | -| `AFTableManager` | `table_manager` | -| `AFIContainer / AFCContainer` | `container / container_impl` | -| `AFITable / AFCTable` | `table / table_impl` | -| `AFIRow / AFCRow` | `row / row_impl` | +Kernel 公开接口位于 `include/ark/kernel/`。配置工具生成 C++ 的流程见[配置工具](tools_CN.md)，协议消息见 [Protobuf](../reference/protobuf_CN.md)。 -下方完整保留旧文章的字段说明、管理器关系和结构图。其 AF 前缀类型及成员布局是历史实现快照；使用当前接口时，应以对应公开头文件为准，不能把这些私有成员布局当作稳定 API。 +![实体字段、表格、容器与元数据的关系](../assets/entity-data-model_CN.svg) -
-原数据结构设计与字段说明 +## 数据定义 -`ARK` 使用数据和定义分离的策略 数据定义包含名字 其对应的下标 类型和是否存储等特征 数据实体包含一个指向对应定义的指针和具体的值 对象中属性用数据的下标和值的映射存储 +| 定义 | 描述 | 运行时值 | +| --- | --- | --- | +| `node_meta` | 字段名、索引、值类型与标记 | `node`，通过 `entity` 或 `row` 访问 | +| `table_meta` | 表名、索引、行类型与标记 | 包含 `row` 的 `table` | +| `container_meta` | 容器名、索引、允许的子实体类型与标记 | 保存子实体的 `container` | +| `class_meta` | 类名、字段索引映射及上述三类定义集合 | `entity` 或配置 `static_entity` | -## 数据配置生成 - -`ARK` 通过`build/tools`文件夹下的工具`gen-config`把`build/resource/excel`下的文件生成对应的数据定义文件和配置文件 分别放在`build/resource/meta`和`build/resource/server` 并且在`build/resource/code`生成类的属性名和下标的接口 - -### 数据定义 - -有四个数据定义类 - -1. `AFNodeMeta` 对象的属性定义 - -- `name_` 属性名 `string` -- `type_` 类型 `enum class ArkDataType` -- `index_` 下标 `uint32` -- `mask_` 是否存储同步等特性 `std::bitset` - -2. `AFTableMeta` 表结构定义 - -- `name_` 表名 `string` -- `index_` 下标 `uint32` -- `type_name_` 表对应的`AFClassMeta` 名称 `string` -- `class_meta_` 对应的`AFClassMeta` `ARK_SHARE_PTR` -- `mask_` 是否存储同步等特性 `std::bitset` - -3. `AFContainerMeta` 容器定义(用来存放对象 借以实现复杂数据结构) - -- `name_` 容器名 `string` -- `index_` 下标 `uint32` -- `class_name_` 容器容纳的对象名 `string` - -4. `AFClassMeta` 类结构定义 - -- `name_` 类名 `string` -- `res_path_` 资源路径 string -- `name_index_list_` 字段名和下表映射 `map` -- `data_meta_list_` 属性映射 `map` -- `table_meta_list_` 表映射 `map` -- `container_meta_list_` 容器映射 `map` -- `class_meta_call_back_` 函数回调 `pointer` - -### 数据实体 - -数据实体有两个 - -1. `AFCStaticEntity` 配置数据实体类 对应接口类`AFIStaticEntity ` - -- `config_id_` 配置id `int` (因为配置id通用且需频繁访问 所以单独列出以提高访问效率) -- `m_pNodeManager` 属性管理器 `ARK_SHARE_PTR` +元数据是共享定义，不是某个实体的可变状态。表的行类型定义各列，容器中的实体则有各自的 ID；容器不是表行，也不是无类型字典。根据应用需要的操作与所有权选择结构。 -2. `AFCEntity ` 对象实体类 对应接口类`AFIEntity ` +## 访问值前先查定义 -- `guid_` 唯一编号 `AFGUID` -- `config_id_` 配置id `int` -- `parent_container_` 所属容器指针 `ARK_SHARE_PTR` -- `map_entity_id_` 地图实体id `int` -- `custom_data_list_` 自定义属性 `hashmap` (可以手动添加和删除属性 无需在文件中先定义好) -- `m_pNodeManager` 属性管理器 `ARK_SHARE_PTR` -- `m_pTableManager` 表管理器 `ARK_SHARE_PTR` -- `m_pContainerManager` 容器管理器 `ARK_SHARE_PTR` -- `m_pEventManager` 事件管理器 `ARK_SHARE_PTR` +元数据模块在初始化时加载定义资源。先确认类与字段存在，再使用与定义类型匹配的访问接口： -其中用到的几个类如下 +```cpp +#include +#include -- `AFNodeManager` 属性管理类 用来管理对象的属性 +#include "ark/kernel/class_meta_module.hpp" - ```cpp - using DataList = AFMap; +bool is_int32_field(ark::class_meta_module& schemas, const std::string& class_name, std::uint32_t index) { + auto schema = schemas.find_meta(class_name); + if (schema == nullptr) + { + return false; + } + auto field = schema->find_data_meta(index); + return field != nullptr && field->get_type() == ark::data_type::dt_int32; +} +``` - // class meta - ARK_SHARE_PTR class_meta_{nullptr}; +`entity::get_node_type()` 可以检查运行时字段的定义类型，再使用 `get_int32()` / `set_int32()`、`get_string()` / `set_string()` 或相应类型接口。零值与空字符串都是合法值，不能据此可靠地判断实体或字段是否缺失。 - // call back - NODE_COMPONENT_FUNCTOR func_; +## 操作表格与行 - // data list - DataList data_list_; - ``` +表格来自已经声明的表元数据。下列函数查找或新增一行，并写入已知的 int32 列。调用者提供定义中的索引，函数不会新建定义或根据值猜测列类型。 -- `AFTableManager` 表管理类 用来管理表 包括创建查找等操作 +```cpp +#include - ```cpp - using TableList = AFMap; +#include "ark/kernel/entity.hpp" +#include "ark/kernel/table.hpp" - // class meta - ARK_SHARE_PTR class_meta_{nullptr}; +bool set_row_value(ark::entity& owner, std::uint32_t table_index, + std::uint32_t row_index, std::uint32_t column_index, std::int32_t value) { + auto* table = owner.find_table(table_index); + if (table == nullptr || table->get_col_type(column_index) != ark::data_type::dt_int32) + { + return false; + } + auto* row = table->find_row(row_index); + if (row == nullptr) + { + row = table->add_row(row_index); + } + return row != nullptr && row->set_int32(column_index, value); +} +``` - // table list - TableList table_list_; - ``` +`find_table()`、`find_row()` 与 `add_row()` 返回借用指针。调用 `remove_row()`、`clear()` 后不再保留原行指针，所属实体销毁后也不再使用表指针。行 ID 与列索引是不同标识。非零行 ID 指定某一行，`add_row(0)` 则分配行 ID。需要变更通知时，在修改前注册表回调。 -- `AFIContainerManager` 容器管理接口类 对应`AFCContainerManager` 用来管理容器 包括创建查找等操作 +## 操作子实体 - ```cpp - // container - using ContainerList = AFSmartPtrMap; - ContainerList container_data_; - ``` +`entity::find_container(index)` 返回容器对象或空值。使用 `kernel_module::create_container_entity(parent_id, container_index, class_name, config_id)` 创建符合定义的子实体，并检查返回值；父实体、容器定义、类以及可选的同类配置必须存在。 -- `AFIContainer` 容器接口类 对应`AFCContainer` 用于复杂结构 可以存放其它子对象 +使用 `container::find(slot)` 或按子实体 ID 查找放置位置。`place()`、`swap()` 修改放置关系，`remove()` 与 `destroy()` 是不同操作，需根据应用要移除关系还是销毁实体来选择。保留 `shared_ptr` 不代表该实体仍在 Kernel 中注册；需要确认存活注册时，应按 ID 再查一次。 - ```cpp - using EntityDataList = AFSmartPtrMap; +## 配置与运行时所有权 - // contain entity class meta - ARK_SHARE_PTR container_meta_{nullptr}; +`static_entity` 表示已加载的配置记录，`entity` 进一步提供运行时标识、可变节点、表格、容器和事件行为。普通实体创建使用配置作为默认值，并保留显式初始化参数；之后修改实体不会改变原配置记录。详见[数据驱动创建](../concepts/data-driven_CN.md)。 - // index start - uint32_t current_index_{0u}; +`node_manager`、`table_manager` 与 `container_manager` 管理相应运行时集合。应用通常通过实体、表格和容器公开接口操作，不依赖管理器内部或 `*_impl` 成员布局。借用指针与回调机制也不代表可以从任意线程并发修改对象。 - // parent id - AFGUID parent_{NULL_GUID}; - - // entity data - EntityDataList entity_data_list_; - ``` - -- `AFIEventManager` 事件管理类 处理对象的事件 - -- `AFINode` 属性接口类 对应`AFCNodeTypeName`(`TypeName`是基本类型名) 用来存放属性的值和对应的定义 - - ```cpp - // meta - ARK_SHARE_PTR data_meta_{nullptr}; - - // value - TypeName data_{TypeName()}; - ``` - -- `AFITable` 表接口类 对应`AFCTable` - - ```cpp - using TableData = AFMap; - - // object unique guid - AFGUID guid_{NULL_GUID}; - - // table meta - ARK_SHARE_PTR table_meta_{nullptr}; - - // current row - uint32_t current_row{0u}; - - // table data - TableData data_; - ``` - -- `AFIRow` 表行接口类 对应`AFCRow` - - ```cpp - // row - uint32_t row_{0u}; - - // data - ARK_SHARE_PTR m_pNodeManager{nullptr}; - ``` - -### 结构图 +## 数据配置生成 -![data structure](../assets/data-structure.png) +现有[配置工具](tools_CN.md)生成 XML 元数据、静态值与 C++ 字段索引定义。修改定义时保持三者一致。保存或同步标记仍需要应用决定持久化与交付策略，不会自动完成存储或复制。 -
+完整创建、类型化访问、回调与转换示例见 [Kernel 参考](../reference/kernel_CN.md)，模块可用阶段见[应用架构](../concepts/application-architecture_CN.md)。历史 AF 前缀布局保存在[原始文章](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/zh-cn/data-structure.md)，这些内部布局不是当前 API 契约。 diff --git a/docs/project/data-design.md b/docs/project/data-design.md index e2a10826a..3c7df2280 100644 --- a/docs/project/data-design.md +++ b/docs/project/data-design.md @@ -1,49 +1,39 @@ -# 新的设计思路 +# Data model design notes -## 数据管理 + -### MetaEntityClassSetting +## Separate definitions from values -class_name -multi-MetaEntityDataSetting +The sketch proposed a general data value with references to class-level and field-level metadata, plus a parent relationship. It split metadata into two purposes: -### MetaConfigClassSetting +| Historical name | Intended purpose | +| --- | --- | +| `MetaEntityClassSetting` | A class name and multiple entity-field definitions | +| `MetaConfigClassSetting` | A class name and multiple configuration-field definitions | +| `MetaEntityDataSetting` | A field type, masks and possible function/script behavior | +| `MetaConfigDataSetting` | A field type and references, without entity masks or function behavior | -class_name -multi-MetaConfigDataSetting +![Historical data-model concept](../assets/draft-data-model.svg) -### MetaEntityDataSetting +The proposed value forms included Boolean, enum, numeric and string values, structures keyed by field name, arrays of values and tables keyed by an integer. The sketch's parent pointer described a relationship; it did not define allocation, ownership, cycle prevention or thread safety. -包含Type 和 Mask, 函数, 脚本等 +## Relationship to the current model -### MetaConfigDataSetting +Current code separates `class_meta`, `node_meta`, `table_meta` and `container_meta` from runtime data. Static configuration records and mutable entities also have separate interfaces. That existing separation is useful context, but it does not make the sketch's general struct/array value, script hooks or metadata hierarchy available as APIs. -只有类型和refer, 没有mask/其他函数等 +The historical names above do not prescribe new public names. They also do not change field indices, stored records, Protobuf numbers or generated identifiers. The original note listed Unreal4 and KFrame as references without a concrete dependency or compatibility contract. -## 参考 +## Questions before implementation -- Unreal4 -- KFrame +- Which metadata belongs to entity behavior, and which belongs only to reusable configuration values? +- Who owns nested values, and what happens to their parent references during removal, replacement or destruction? +- How do validation, serialization and callbacks handle nested changes and missing references? +- How are existing schemas and saved records migrated without silently changing their meaning? + +These questions need a separate design and tests. No business configuration format or migration mechanism is selected here. Continue with the related [nested-data proposal](data-model-proposal.md). + +The Chinese [original note](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/zh-cn/new-desgin.md) is preserved byte-for-byte in the [source archive](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/README.md). This English page is an explanation of that source, not an invented historical translation file. diff --git a/docs/project/data-design_CN.md b/docs/project/data-design_CN.md index e2a10826a..1c565f749 100644 --- a/docs/project/data-design_CN.md +++ b/docs/project/data-design_CN.md @@ -1,49 +1,39 @@ -# 新的设计思路 +# 数据模型设计说明 -## 数据管理 + -### MetaEntityClassSetting +## 分开描述定义与值 -class_name -multi-MetaEntityDataSetting +草图提出一种通用数据值，分别引用类级与字段级元数据，并保留父级关系。元数据按两种用途划分： -### MetaConfigClassSetting +| 历史名称 | 设想中的用途 | +| --- | --- | +| `MetaEntityClassSetting` | 类名及多个实体字段定义 | +| `MetaConfigClassSetting` | 类名及多个配置字段定义 | +| `MetaEntityDataSetting` | 字段类型、标记，以及可能的函数或脚本行为 | +| `MetaConfigDataSetting` | 字段类型与引用，不包含实体标记或函数行为 | -class_name -multi-MetaConfigDataSetting +![历史数据模型概念](../assets/draft-data-model_CN.svg) -### MetaEntityDataSetting +设想的值类型包括 Boolean、枚举、数值、字符串、按字段名索引的结构、值数组，以及按整数索引的表格。草图中的父指针只描述关系，没有定义内存分配、所有权、循环引用限制或线程安全。 -包含Type 和 Mask, 函数, 脚本等 +## 与当前模型的关系 -### MetaConfigDataSetting +当前代码将 `class_meta`、`node_meta`、`table_meta`、`container_meta` 与运行时数据分开管理，静态配置记录与可变实体也有不同接口。这些已有区分可作为设计背景，但不表示草图中的通用结构或数组值、脚本挂钩和元数据继承体系已成为 API。 -只有类型和refer, 没有mask/其他函数等 +上述历史名称不限定未来公开接口的命名，也不改变字段索引、存储记录、Protobuf 编号或生成标识。原笔记列出 Unreal4、KFrame 作为参考，没有确定具体依赖或兼容契约。 -## 参考 +## 实现前需要明确的问题 -- Unreal4 -- KFrame +- 哪些元数据属于实体行为，哪些仅描述可复用配置值？ +- 嵌套值由谁持有，移除、替换或销毁时如何处理父级引用？ +- 验证、序列化与回调如何处理嵌套变化及缺失引用？ +- 如何迁移已有定义和保存记录，同时保留原有含义？ + +这些问题需要单独设计与测试。本页不选择业务配置格式，也不确定迁移机制。相关思路见[嵌套数据提案](data-model-proposal_CN.md)。 + +中文[原始笔记](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/zh-cn/new-desgin.md)逐字节保留在[源码归档](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/README.md)中。英文页解释同一来源，不伪造历史英文文件。 diff --git a/docs/project/data-model-proposal.md b/docs/project/data-model-proposal.md index b243067b4..1ab275741 100644 --- a/docs/project/data-model-proposal.md +++ b/docs/project/data-model-proposal.md @@ -1,12 +1,35 @@ -# 新的数据结构设计 +# Nested data and configuration proposal -## 多层数据结构 + -核心配置分为两份 +## Intended direction -- EntityClass.meta 只有实例对象在里面 -- ConfigClass.meta && Config.config 配置表，表头为meta, 内容为config +The original note wanted the data abstraction to represent nested structures rather than only a fixed set of basic value forms. For example, a business record could contain a structure, an array or a keyed collection of other values. This describes a modeling goal; it does not define wire encoding, persistence layout or C++ ownership. + +![Proposed separation of metadata and nested values](../assets/draft-data-model.svg) + +The note also separated runtime entity definitions from reusable configuration definitions and their values: + +| Historical filename | Proposed meaning | +| --- | --- | +| `EntityClass.meta` | Definitions for runtime instance objects | +| `ConfigClass.meta` | Configuration record schema, analogous to table columns | +| `Config.config` | Configuration records using that schema | + +These are names in the old proposal. They are not new files required by the current loader. Current resource lists are `resource/meta/entity_class.config` and `resource/meta/config_class.config`; see [data-driven loading](../concepts/data-driven.md). + +## Current interfaces and the proposed extension + +Current Kernel supports typed entity nodes, schema-backed table rows and containers of child entities. Use those interfaces for present applications. A container of entities is not automatically a general array of arbitrary nested values, and a Protobuf conversion function does not define migration for a future value hierarchy. + +A future extension would need to specify type validation, nested references, ownership and removal behavior, change notification, serialization and compatibility. It must also say how class/field indices and existing configuration records map to the new structures. The proposal does not yet supply those rules or a safe reload protocol. + +## Migration boundary + +Keep existing metadata names, generated indices, saved data and external message contracts consistent until a migration has been explicitly designed and tested. Service-process configuration and business data are separate concerns; choosing a service manifest format does not select the representation of these entity/configuration resources. + +Use [data structures](../guides/data-structures.md) for today's model and [the related design note](data-design.md) for the metadata sketch. The Chinese [original source](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/design/data.md) is preserved in the [source archive](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/README.md); no historical English source is claimed. diff --git a/docs/project/data-model-proposal_CN.md b/docs/project/data-model-proposal_CN.md index b243067b4..8e22ab361 100644 --- a/docs/project/data-model-proposal_CN.md +++ b/docs/project/data-model-proposal_CN.md @@ -1,12 +1,35 @@ -# 新的数据结构设计 +# 嵌套数据与配置提案 -## 多层数据结构 + -核心配置分为两份 +## 设计方向 -- EntityClass.meta 只有实例对象在里面 -- ConfigClass.meta && Config.config 配置表，表头为meta, 内容为config +原笔记希望数据抽象能够表示嵌套结构，而不局限于固定的基础值类型。例如一份业务记录可以包含结构、数组或带键的值集合。这是数据建模目标，没有定义线格式、持久化布局或 C++ 所有权。 + +![元数据与嵌套值的分离设想](../assets/draft-data-model_CN.svg) + +笔记同时区分运行时实体定义，以及可复用配置的定义与值： + +| 历史文件名 | 设想中的含义 | +| --- | --- | +| `EntityClass.meta` | 运行时实例对象的定义 | +| `ConfigClass.meta` | 配置记录定义，类似表格的列 | +| `Config.config` | 使用上述定义的配置记录 | + +这些是旧提案中的名称，不是当前加载器新要求的文件。现有资源清单是 `resource/meta/entity_class.config` 和 `resource/meta/config_class.config`，详见[数据驱动加载](../concepts/data-driven_CN.md)。 + +## 当前接口与拟扩展能力 + +当前 Kernel 提供类型化实体节点、带定义的表行，以及保存子实体的容器。现阶段应用使用这些接口。实体容器并不自动等同于任意嵌套值的通用数组，Protobuf 转换函数也不会为未来的值体系定义迁移规则。 + +后续扩展需要明确类型验证、嵌套引用、所有权与移除行为、变更通知、序列化及兼容性，还需要说明类与字段索引、已有配置记录如何映射到新结构。此提案尚未给出这些规则，也没有定义安全重载协议。 + +## 迁移边界 + +在明确设计并验证迁移前，保持现有元数据名称、生成索引、保存数据和外部消息契约一致。服务进程配置与业务数据是不同问题；选择服务清单格式，不代表同时选择实体或配置资源的表示方式。 + +现有模型见[数据结构](../guides/data-structures_CN.md)，元数据草图见[相关设计说明](data-design_CN.md)。中文[原始来源](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/design/data.md)保留在[源码归档](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/README.md)中，不声称存在历史英文原文。 diff --git a/docs/project/network-design.md b/docs/project/network-design.md index d88302427..d16f67822 100644 --- a/docs/project/network-design.md +++ b/docs/project/network-design.md @@ -1,26 +1,37 @@ -# 新的改进设计思路 +# Cluster, router and zone design notes -## 架构设计 + -## 网络拓扑设计 +## Proposed process responsibilities -zone 内的网络拓扑均由world来管理 -cluster 内的网络拓扑均由master来管理 +The note divided processes into three levels: -zone内的消息内部消化 +| Level | Intended role | +| --- | --- | +| `cluster` | Services shared across zones; Master manages the cluster topology | +| `router` | A message-forwarding intermediary between zone and cluster processes | +| `zone` | Per-zone processes; World manages the zone topology | -zone发往cluster的消息，可以直接发往router，由router根据包头中的dst_bus_id来转发 +![Reference roles for cluster, router and zones](../assets/server-topology.svg) -cluster的所有进程都需要连master和router +The proposed routing rules kept zone-internal traffic within its zone. Messages destined for the cluster could go through Router, which would select a route using the header's historical `dst_bus_id` destination. All cluster processes would connect to Master and Router, while selected zone processes would connect to Router. -zone内的部分进程链接router +These are proposed responsibilities and connection rules. They do not themselves define authentication, route convergence, retry behavior, congestion control, duplicate delivery or state recovery. The [server architecture](../concepts/server-architecture.md) explains how the repository's example roles relate to a deployment reference. -## log设计 +## Historical remote-logging idea -所有的进程都需要先链接log server后才能开始业务功能，这样可以保证所有的log都输出到远端去，log client插件需要有一个配置，表示远端log server ip-port，以及log格式 +The note also proposed that every process establish a connection to a log server before beginning business work. A log-client configuration would contain the remote address/port and log format. + +That startup gate is an idea, not an implemented framework-wide requirement. A successful initial connection would not by itself guarantee that all subsequent logs are delivered or retained. Delivery acknowledgement, buffering limits, backpressure, authentication, reconnect behavior and what to do when logging is unavailable still require a defined policy. This page does not choose one. + +## Use the current framework without assuming the proposal + +Applications can compose the existing role plugins and configure their network/Bus relationships. Use their actual configuration and APIs rather than inferring behavior from a process name. Neither Consul nor a custom Registry becomes mandatory merely because a deployment uses multiple zones. Registry consistency, leases and failover remain separate design work. + +This proposal does not establish cross-host capacity, automatic topology recovery, storage consistency or lossless remote logs. Preserve those as explicit deployment tests and design requirements; see [benchmarks and acceptance](../performance/benchmark.md). + +The Chinese [original note](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/design/network.md) is retained in the [source archive](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/README.md). The English page is a current explanation of that historical text, not evidence of an English original or an accepted implementation decision. diff --git a/docs/project/network-design_CN.md b/docs/project/network-design_CN.md index d88302427..23f9b7ceb 100644 --- a/docs/project/network-design_CN.md +++ b/docs/project/network-design_CN.md @@ -1,26 +1,37 @@ -# 新的改进设计思路 +# Cluster、Router 与 Zone 设计说明 -## 架构设计 + -## 网络拓扑设计 +## 提议中的进程职责 -zone 内的网络拓扑均由world来管理 -cluster 内的网络拓扑均由master来管理 +原笔记将进程分为三个层次： -zone内的消息内部消化 +| 层次 | 设想中的职责 | +| --- | --- | +| `cluster` | 跨区共享服务，由 Master 管理集群拓扑 | +| `router` | 区服与集群进程之间的消息转发中间层 | +| `zone` | 小区进程，由 World 管理区内拓扑 | -zone发往cluster的消息，可以直接发往router，由router根据包头中的dst_bus_id来转发 +![Cluster、Router 与 Zone 的参考职责](../assets/server-topology_CN.svg) -cluster的所有进程都需要连master和router +设想中的路由规则要求区内消息在本区处理。发往集群的消息可以经过 Router，由其依据历史包头中的 `dst_bus_id` 目标选择路由。集群内所有进程连接 Master 与 Router，部分区服进程连接 Router。 -zone内的部分进程链接router +这些是职责与连接关系的提议，没有由此定义鉴权、路由收敛、重试、拥塞控制、重复交付或状态恢复。[服务器架构](../concepts/server-architecture_CN.md)说明仓库示例角色与部署参考之间的关系。 -## log设计 +## 历史远端日志设想 -所有的进程都需要先链接log server后才能开始业务功能，这样可以保证所有的log都输出到远端去，log client插件需要有一个配置，表示远端log server ip-port，以及log格式 +笔记还提出：所有进程先与日志服务建立连接，再开始业务工作；日志客户端配置包含远端地址、端口与日志格式。 + +这个启动门槛是设想，不是框架已实现的全局要求。首次连接成功，本身也无法保证后续全部日志被交付或保留。交付确认、缓冲限额、背压、鉴权、重连，以及日志服务不可用时的处理，都仍需明确策略。本页不代替这些选型。 + +## 使用当前框架时的边界 + +应用可以组合现有角色插件，并配置网络与 Bus 关系。应依据实际配置和 API 使用，不能从进程名称推断行为。部署多个区服不会自动要求使用 Consul 或自研 Registry；Registry 的一致性、租约与故障切换仍是独立设计事项。 + +此提案不证明跨主机容量、拓扑自动恢复、存储一致性或远端日志无丢失。这些需要明确的设计要求与部署测试，详见[基准测试与验收](../performance/benchmark_CN.md)。 + +中文[原始笔记](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/design/network.md)保留在[源码归档](https://github.com/OpenArkStudio/ark/blob/main/docs/site/legacy-source/README.md)中。英文页是对历史内容的现代说明，不表示存在历史英文原文，也不表示已经接受其中的实现决策。 diff --git a/docs/site/legacy-source/.gitattributes b/docs/site/legacy-source/.gitattributes new file mode 100644 index 000000000..45227233a --- /dev/null +++ b/docs/site/legacy-source/.gitattributes @@ -0,0 +1,2 @@ +# Preserve original document bytes across platforms and Git line-ending settings. +*.md -text diff --git a/docs/site/legacy-source/README.md b/docs/site/legacy-source/README.md new file mode 100644 index 000000000..36061bfdc --- /dev/null +++ b/docs/site/legacy-source/README.md @@ -0,0 +1,60 @@ +# Original Docsify source archive + +Snapshot: `d2b1f31ee7ac77aa8c273a38ed7c60c0b534084d` + +This directory preserves the 40 articles identified by `scripts/migration-source.mjs`. Each file was exported as raw bytes from that Git snapshot and its original path; no translation, newline normalization, typo correction or link rewriting was applied. The snapshot identifier is provenance, not a claim about a remote repository or a new license. Any notices in the original files remain unchanged. + +The archive-local `.gitattributes` disables line-ending conversion for Markdown, so checkout settings cannot rewrite the stored source bytes. Many originals intentionally have no final newline. + +These are historical source records, not current API documentation. The three design sources `zh-cn/new-desgin.md`, `design/data.md` and `design/network.md` are Chinese; their English modern guides are translations/explanations, not invented historical English files. Original relative image/link paths are retained literally. Use the modern guides for current diagrams and links. + +The site content preparer skips the entire `docs/site/` directory, so this archive is not included in current navigation, search or AI Markdown/llms exports. Open the source files in Git when tracing historical wording. + +Run `node --test scripts/legacy-source.test.mjs` from `docs/site/`, or run the normal `npm run check`. The test verifies the snapshot identifier, every mapping and every file digest without requiring the old Git object in CI. + +原文按下表路径与快照逐字节保留，不进行翻译、换行转换或链接改写。归档不表示当前功能，不进入现代站点导航与 AI 文档。三份设计原文只有中文，现代英文说明不伪造历史来源。原文件中的声明保持原样，本文不推断远端仓库或新增许可证。 + +## Source mapping and checksums + +| Original path | Current content path | SHA256 | +| --- | --- | --- | +| `design/data.md` | `docs/project/data-model-proposal_CN.md` | `714d3233a81640f7077ffedf812323df18b9e35e1ce16c5ce410ff0cc66cf30f` | +| `design/network.md` | `docs/project/network-design_CN.md` | `373eb3e87967ec0b591a70995afe35e28383b8d40d31c94fb6c76ce2ade520e6` | +| `en-us/app-architecture.md` | `docs/concepts/application-architecture.md` | `951713661ce183c7ce1042d29603537ce5c080774d80de56fa3e7b9ed757abba` | +| `en-us/app.md` | `docs/guides/applications.md` | `6a4a8905456c1212f2296045c31e72805b85c144015075c2a2bb5c903f0d5b7b` | +| `en-us/benchmark.md` | `docs/performance/benchmark.md` | `4c3a4ac70a96043e9588760300309244adea1c3062d2ca439907dfc43d2287ab` | +| `en-us/bus-plugin.md` | `docs/reference/bus.md` | `279e1e9868085f2a23dbb3c1a72d63eac47fca1da86cea613b7a306c37f47477` | +| `en-us/changelog.md` | `docs/project/changelog.md` | `20ec0d28f438fa88b118cc484b2f13d1a8effb34b9021e9b390644246ed3ed3a` | +| `en-us/concept.md` | `docs/concepts/glossary.md` | `d6c2d9e75249a52c3b1a3b3e12f5006ddef68e4a51c72d081a0cc9790869475a` | +| `en-us/create-new-module.md` | `docs/guides/modules.md` | `d4c8b846c716924246c5e972d838415b3e57b966a99ef5df80562dffdef4100d` | +| `en-us/create-new-plugin.md` | `docs/guides/plugins.md` | `d9fb354f3b891bd6dad4f8189c4b19533897688f32084ea479b87e17f3df36a8` | +| `en-us/data-driven.md` | `docs/concepts/data-driven.md` | `457148d84344669a675e6f2d9ca647f0690c465c83042e899fc1dc8ca0da22bb` | +| `en-us/data-structure.md` | `docs/guides/data-structures.md` | `4a127c922a721ce05242f6748ee6d753d92711cf16ab9c79ee9e524b52adb259` | +| `en-us/directory-structure.md` | `docs/reference/directory-structure.md` | `c89e8ba1f08b230b143ad367f8aa7f3fd2a638d13ba3a554dc9dbc4999d39b9a` | +| `en-us/faq.md` | `docs/project/faq.md` | `3a80b1c867cf3794e677302468fa61b4fc77d3730927bbe97d66caaee7c61f98` | +| `en-us/kernel-plugin.md` | `docs/reference/kernel.md` | `c17d35d793fa4d04ea1bbadd9188e678903a4996301b9bf4eee8b720aff1eebc` | +| `en-us/net-plugin.md` | `docs/reference/network.md` | `0fe6d755e093cb7bd32ad9a15d3189e81be2a68d83004e0d27364b0587e7f98e` | +| `en-us/plan.md` | `docs/project/roadmap.md` | `615e7d945ee81faf21ee62426f7b485df30002d849fd97a5681bf24f2003404a` | +| `en-us/quick-start.md` | `docs/get-started/quick-start.md` | `8abb9f2e0ed4b30d40c716e934b1ffb4431455f0eca3de27d8da7f0fea4ee22a` | +| `en-us/server-architecture.md` | `docs/concepts/server-architecture.md` | `2677fa2414719c5ca003ab5eda8ba45f655bc3ebe7ca9abfe6c5e0c560123e49` | +| `en-us/tools.md` | `docs/guides/tools.md` | `6ae8c3fff68753ff29faf59997d3846fea749eedb356ad1266e8ab83dbca7927` | +| `zh-cn/app-architecture.md` | `docs/concepts/application-architecture_CN.md` | `d470fd8e545f9f05c38602430d432f1721dfd6aa6089faaa39ab20473a0100df` | +| `zh-cn/app.md` | `docs/guides/applications_CN.md` | `20d89185abe66b752b9e564413676eea6d6a8f9e42f16b0139d962bed50fc3ba` | +| `zh-cn/benchmark.md` | `docs/performance/benchmark_CN.md` | `b6e7b8e2655171a9ed9f0718f2460034311427bdb1fa3e143b134352b0be2114` | +| `zh-cn/bus-plugin.md` | `docs/reference/bus_CN.md` | `d72a1308328503cfe51d268004956819d625ec62c8344d08abeb100bf4b18c98` | +| `zh-cn/changelog.md` | `docs/project/changelog_CN.md` | `f1a3786c05515ec017843dff468cf367b2cdbe6a6f2cb7d93692385f6ab7ddb8` | +| `zh-cn/coding-guide.md` | `docs/project/code-style_CN.md` | `0dfb9817311b67791cd1b8edf418e42ffdd279630247ec1ceeb4946bb7cd9e7d` | +| `zh-cn/concept.md` | `docs/concepts/glossary_CN.md` | `d6c2d9e75249a52c3b1a3b3e12f5006ddef68e4a51c72d081a0cc9790869475a` | +| `zh-cn/create-new-module.md` | `docs/guides/modules_CN.md` | `6ced0eb07830db520e440ecee10219939202b876b148e68849f1d49723d7624a` | +| `zh-cn/create-new-plugin.md` | `docs/guides/plugins_CN.md` | `43999ed09f4f672ef03271f4ee29b7a2625f0f9b8402894bcedb9e2c3d810139` | +| `zh-cn/data-driven.md` | `docs/concepts/data-driven_CN.md` | `dfb088dbea3e981960d08e3e897392a6aa7dd4473be02a90db980670de6b5d2f` | +| `zh-cn/data-structure.md` | `docs/guides/data-structures_CN.md` | `4a127c922a721ce05242f6748ee6d753d92711cf16ab9c79ee9e524b52adb259` | +| `zh-cn/directory-structure.md` | `docs/reference/directory-structure_CN.md` | `1b0985c1486fc1a23d36f1350fcf467e31b6f0324d551fd82c19d3d3975cc10a` | +| `zh-cn/faq.md` | `docs/project/faq_CN.md` | `3f42a7a5f05c759484dba76bc08c4b04f7fae82d8fb66a64ff81486aacfc8b36` | +| `zh-cn/kernel-plugin.md` | `docs/reference/kernel_CN.md` | `c17d35d793fa4d04ea1bbadd9188e678903a4996301b9bf4eee8b720aff1eebc` | +| `zh-cn/net-plugin.md` | `docs/reference/network_CN.md` | `f34464371c3332d4410d6440ee25163851e5a22ac67e0763cb3af544e01c4754` | +| `zh-cn/new-desgin.md` | `docs/project/data-design_CN.md` | `5fff2197187e4224d4e32b13813d28a05f5fc6addcd2e6773baa5827567c024a` | +| `zh-cn/plan.md` | `docs/project/roadmap_CN.md` | `791bb943d2d173ab8f5942d8acb21b69fcdc3a57cf145ba4df03388cc639a146` | +| `zh-cn/quick-start.md` | `docs/get-started/quick-start_CN.md` | `df26605b857aaf8a73a5a0f72b036e0742242f874463ea6340dd50037890cde2` | +| `zh-cn/server-architecture.md` | `docs/concepts/server-architecture_CN.md` | `a84ebd78455a5f2844dfc16a409fc655f15755aa99fd9c0337a89398d3f4d63a` | +| `zh-cn/tools.md` | `docs/guides/tools_CN.md` | `b0757f3df92fcff965083dcf420eab9c37142e551618869a98032980ff0bb3b3` | diff --git a/docs/site/legacy-source/design/data.md b/docs/site/legacy-source/design/data.md new file mode 100644 index 000000000..7ed8ef48e --- /dev/null +++ b/docs/site/legacy-source/design/data.md @@ -0,0 +1,12 @@ +# 新的数据结构设计 + +## 多层数据结构 + +AFIData不再是仅有的几种数据结构，支持嵌套复杂结构 + +## 配置结构修改 + +核心配置分为两份 + +- EntityClass.meta 只有实例对象在里面 +- ConfigClass.meta && Config.config 配置表，表头为meta, 内容为config \ No newline at end of file diff --git a/docs/site/legacy-source/design/network.md b/docs/site/legacy-source/design/network.md new file mode 100644 index 000000000..e891e3cdd --- /dev/null +++ b/docs/site/legacy-source/design/network.md @@ -0,0 +1,26 @@ +# 新的改进设计思路 + +## 架构设计 + +分为三层 + +- cluster 全区全服进程 +- router zone <-> cluster的中间层，主要做协议转发 +- zone 小区进程 + +## 网络拓扑设计 + +zone 内的网络拓扑均由world来管理 +cluster 内的网络拓扑均由master来管理 + +zone内的消息内部消化 + +zone发往cluster的消息，可以直接发往router，由router根据包头中的dst_bus_id来转发 + +cluster的所有进程都需要连master和router + +zone内的部分进程链接router + +## log设计 + +所有的进程都需要先链接log server后才能开始业务功能，这样可以保证所有的log都输出到远端去，log client插件需要有一个配置，表示远端log server ip-port，以及log格式 \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/app-architecture.md b/docs/site/legacy-source/en-us/app-architecture.md new file mode 100644 index 000000000..d36fc4874 --- /dev/null +++ b/docs/site/legacy-source/en-us/app-architecture.md @@ -0,0 +1 @@ +# Application architecture \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/app.md b/docs/site/legacy-source/en-us/app.md new file mode 100644 index 000000000..b03db8306 --- /dev/null +++ b/docs/site/legacy-source/en-us/app.md @@ -0,0 +1 @@ +# The loader of launching plugins \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/benchmark.md b/docs/site/legacy-source/en-us/benchmark.md new file mode 100644 index 000000000..96008c605 --- /dev/null +++ b/docs/site/legacy-source/en-us/benchmark.md @@ -0,0 +1 @@ +# Benchmark \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/bus-plugin.md b/docs/site/legacy-source/en-us/bus-plugin.md new file mode 100644 index 000000000..027abcaf7 --- /dev/null +++ b/docs/site/legacy-source/en-us/bus-plugin.md @@ -0,0 +1 @@ +# Bus plugin \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/changelog.md b/docs/site/legacy-source/en-us/changelog.md new file mode 100644 index 000000000..21b029870 --- /dev/null +++ b/docs/site/legacy-source/en-us/changelog.md @@ -0,0 +1,88 @@ +# changelogs + +## version 0.9 + +- Fix `HeartBeatManager` remove mistake(Thanks @sks) +- Add `DateTime` +- Fix sonar bad smells +- Replace `AFBitValue` with `std::bitset` +- Add `random` functions +- Replace `easylogging++` with `spdlog` +- Add BusPlugin(use `busid` as server id and communicate, for now not totally finished) +- Update `Proto` library to `ProtoPlugin` +- Update `Net` library to `NetPlugin` +- Update `brynet` to the newest version +- Refactoring the net plugin +- Add DataTable callback when `DataTable.Add/Set/Del(data)` +- Modify table row index +- Modify module register order and fix config's bug +- Optimise - Don't load DataNode in AFConfigModule when the node value is the default +- Add AFCMsgModule(not finished yet) + +## version 0.8 + +- Replace `evpp` with `brynet` for reducing dependence +- Add `AFCronScheduleModule`, using `cron` syntax +- Add `WebSocket` support +- Replace `easylogging++` with `spdlog` +- Add `SonarCloud` check +- Add `Codecov` test +- Fix some warnings +- Fix some code smells of SonarCloud +- Fix GUID bug +- Fix some known bugs + +## version 0.7 + +- Restructure log module +- Update to VS2017 as default IDE in windows +- Add function `strlcpy` +- Use a new memory pool +- Fix `AFTimer` bugs +- Reduce `.git` disk usage +- Fix Net bugs +- Fix parameters warnings +- Fix tools, config id can be a number +- Rename Example files + +## version 0.6 + +- Change Mem allocation +- Add Timer Module(Using time wheel) +- Modify Plugin DLL entry and exit functions by using macro `ARK_DLL_PLUGIN_ENTRY(Plugin Class)` +- Add `ARK_STATIC_ASSERT` +- Add launch parameters for launching multi-processes +- Use `std::is_base_of` to instead self derived class check + +## version 0.5 + +- Fix some memory bugs +- Add memory pool and allocation +- Add wiki(Unfinished) +- Restructure file directories +- Add a new file processing tool + +## version 0.4 + +- Unified concept, Property -> DataNode Record -> DataTable +- Unified configurations +- Update Google.Protobuffer 3.x +- Fix some bugs + +## version 0.3 + +- Fix msg head bugs +- Rename some files + +## version 0.2 + +- Modify base data structure +- Modify the performance of the network +- Modify directories structure +- Add CMake support(Linux platform is testing) +- Modify the compiling way of **Dep** +- Modify GUID to 128 bits + +## version 0.1 + +- First release \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/concept.md b/docs/site/legacy-source/en-us/concept.md new file mode 100644 index 000000000..6d8cac0e6 --- /dev/null +++ b/docs/site/legacy-source/en-us/concept.md @@ -0,0 +1,41 @@ +# Concepts + +## Module(模块) + +表示一类逻辑业务的合集, 相对来说功能比较集中, 可以做到低耦合, 并且可以通过`IOP`(面向接口编程)的方式来给其他模块提供耦合功能.例如LogModule等. + +## Plugin(插件) + +表示一系列Module的集合, 按照更大的业务来分类, 例如GameLogic插件, Navimesh插件等. + +## Application(应用) + +表示一个独立的完整功能的进程, 可以包含大量插件, 例如GameServer等. + +## DataNode + +表示一维数据, 通常用来表示Entity附带的任意一维数据结构, 当前可以为常用内置数据类型(`bool` `int` `int64` `double` `float` `string` `GUID`). 例如`PlayerEnity`附带的HP MP等数据. + +## DataTable + +表示二维数据, 通常用来表示Entity附带的任意二维数据结构,结构与Microsoft Excel的二维结构类似, 包含`Row`和`Column`, 并且结构可以通过Excel动态传入, Table中任意Cell可以为常用内置数据类型(`bool` `int` `int64` `double` `float` `string` `GUID`). 例如`PlayerEnity`附带的`ItemTable`. + +## Entity(实体) + +表示游戏内动态创建的任意实体对象, 该实体对象通常携带大量`DataNode`和`DataTable`, 例如：PlayerEntity、MonsterEntity、NPCEntity等. + +## App工具 + +用来加载多个Plugin动态链接库, 从而形成一个Application. + +## GUID + +表示游戏内唯一ID, 并且全区全服不重复, 可以用来做`EntityID`等游戏内有唯一性需求的ID. + +## Event(事件) + +游戏逻辑监听和产生事件, 用来解耦游戏逻辑. + +## Google Proto-buffer + +Google开源的跨平台, 跨语言的数据序列化库, 详见https://github.com/google/protobuf \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/create-new-module.md b/docs/site/legacy-source/en-us/create-new-module.md new file mode 100644 index 000000000..268b62b6f --- /dev/null +++ b/docs/site/legacy-source/en-us/create-new-module.md @@ -0,0 +1,115 @@ +# Create a new module quickly + +## A simple module + +```cpp +#pragma once + +#include "base/AFPluginManager.hpp" +#include "interface/AFIPlugin.hpp" +#include "interface/AFIModule.hpp" +#include "utility/interface/AFITimerModule.hpp" +#include "log/interface/AFILogModule.hpp" +#include "utility/interface/AFIScheduleModule.hpp" +#include "utility/interface/AFIGUIDModule.hpp" + +namespace ark { + +class Sample1Module final : public AFIModule +{ + ARK_DECLARE_MODULE_FUNCTIONS +public: + bool Init() override; + bool PostInit() override; + bool Update() override; + bool PreShut() override; + bool Shut() override; + +protected: + AFITimerModule* m_pTimerModule; + AFILogModule* m_pLogModule; + AFIGUIDModule* m_pGUIDModule; + AFIScheduleModule* m_pScheduleModule; +}; + +} // namespace ark +``` + +Explain: + +- All modules inherits from `AFIModule` +- There are several conventional state machine execution functions in the module class.(Explain later) +- In addition to the variables that have their own logical functions, the main member variables of the module class are other module pointers, which are used to call the functions of other modules.(Please search **Interface oriented programming(IOP)**) + +## Module execution state machine + +As mentioned earlier, all of our modules are inherited from `AFIModule'. The AFIModule mainly contains the following virtual functions executed by plug-ins in different states, as follows + +```cpp +#pragma once + +#include "base/AFPlatform.hpp" +#include "base/AFMacros.hpp" + +namespace ark { + +class AFPluginManager; + +class AFIModule +{ +public: + AFIModule() = default; + virtual ~AFIModule() = default; + + virtual bool Init() { return true; } + virtual bool PostInit() { return true; } + virtual bool CheckConfig() { return true; } + virtual bool PreUpdate() { return true; } + virtual bool Update() { return true; } + virtual bool PreShut() { return true; } + virtual bool Shut() { return true; } + + virtual AFPluginManager* GetPluginManager() const { return nullptr; } + + virtual void SetPluginManager(AFPluginManager* p) + { + // Do nothing in the module interface + } + + virtual const std::string& GetName() const + { + static const std::string null_str = ""; + return null_str; + } + + virtual void SetName(const std::string& value) + { + // Do nothing in the module interface + } +}; + +} // namespace ark +``` + +Module execution flowchart: + +```plantuml +@startuml + +start + :Init; + :PostInit; + :CheckConfig; + :PreUpdate; + +while (Check exit?) is (no) + :Update; +endwhile(yes) + + :PreShut; + :Shut; + +stop + +@enduml +``` \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/create-new-plugin.md b/docs/site/legacy-source/en-us/create-new-plugin.md new file mode 100644 index 000000000..2cd02a4e3 --- /dev/null +++ b/docs/site/legacy-source/en-us/create-new-plugin.md @@ -0,0 +1,50 @@ +# Create a new plugin quickly + +## A simple plugin + +Header file + +```cpp +#pragma once + +#include "interface/AFIPlugin.hpp" +#include "base/AFPluginManager.hpp" + +namespace ark { + +ARK_DECLARE_PLUGIN(Sample1Plugin) + +} // namespace ark +``` + +Source file + +```cpp +#include "Sample1Plugin.h" +#include "Sample1Module.h" + +namespace ark { + +ARK_DECLARE_PLUGIN_DLL_FUNCTION(Sample1Plugin) + +void Sample1Plugin::Install() +{ + ARK_REGISTER_MODULE(Sample1Module, Sample1Module); +} + +void Sample1Plugin::Uninstall() +{ + ARK_DEREGISTER_MODULE(Sample1Module, Sample1Module); +} + +} // namespace ark +``` + +## Plugin description + +The plug-in installs `Install`, and registers the modules in the plug-in one by one through the `RegisterModule` function. + +The plug-in uninstall, and the modules in the plug-in are de-registered from the plug-in one by one through the `DeregisterModule` function. + +> [!ATTENTION] +> There are two class names in module registration and de-registration, the front is `interface class` and the `concrete class` after. \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/data-driven.md b/docs/site/legacy-source/en-us/data-driven.md new file mode 100644 index 000000000..096c459d1 --- /dev/null +++ b/docs/site/legacy-source/en-us/data-driven.md @@ -0,0 +1 @@ +# Data driven \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/data-structure.md b/docs/site/legacy-source/en-us/data-structure.md new file mode 100644 index 000000000..95e8af879 --- /dev/null +++ b/docs/site/legacy-source/en-us/data-structure.md @@ -0,0 +1,162 @@ +# 数据结构说明 + +`ARK` 使用数据和定义分离的策略 数据定义包含名字 其对应的下标 类型和是否存储等特征 数据实体包含一个指向对应定义的指针和具体的值 对象中属性用数据的下标和值的映射存储 + +## 数据配置生成 + +`ARK` 通过`bin/tools`文件夹下的工具`gen-config`把`bin/resource/excel`下的文件生成对应的数据定义文件和配置文件 分别放在`bin/resource/meta`和`bin/resource/server` 并且在`bin/resource/code`生成类的属性名和下标的接口 + +### 数据定义 + +有四个数据定义类 + +1. `AFNodeMeta` 对象的属性定义 + +- `name_` 属性名 `string` +- `type_` 类型 `enum class ArkDataType` +- `index_` 下标 `uint32` +- `mask_` 是否存储同步等特性 `std::bitset` + +2. `AFTableMeta` 表结构定义 + +- `name_` 表名 `string` +- `index_` 下标 `uint32` +- `type_name_` 表对应的`AFClassMeta` 名称 `string` +- `class_meta_` 对应的`AFClassMeta` `ARK_SHARE_PTR` +- `mask_` 是否存储同步等特性 `std::bitset` + +3. `AFContainerMeta` 容器定义(用来存放对象 借以实现复杂数据结构) + +- `name_` 容器名 `string` +- `index_` 下标 `uint32` +- `class_name_` 容器容纳的对象名 `string` + +4. `AFClassMeta` 类结构定义 + +- `name_` 类名 `string` +- `res_path_` 资源路径 string +- `name_index_list_` 字段名和下表映射 `map` +- `data_meta_list_` 属性映射 `map` +- `table_meta_list_` 表映射 `map` +- `container_meta_list_` 容器映射 `map` +- `class_meta_call_back_` 函数回调 `pointer` + +### 数据实体 + +数据实体有两个 + +1. `AFCStaticEntity` 配置数据实体类 对应接口类`AFIStaticEntity ` + +- `config_id_` 配置id `int` (因为配置id通用且需频繁访问 所以单独列出以提高访问效率) +- `m_pNodeManager` 属性管理器 `ARK_SHARE_PTR` + +2. `AFCEntity ` 对象实体类 对应接口类`AFIEntity ` + +- `guid_` 唯一编号 `AFGUID` +- `config_id_` 配置id `int` +- `parent_container_` 所属容器指针 `ARK_SHARE_PTR` +- `map_entity_id_` 地图实体id `int` +- `custom_data_list_` 自定义属性 `hashmap` (可以手动添加和删除属性 无需在文件中先定义好) +- `m_pNodeManager` 属性管理器 `ARK_SHARE_PTR` +- `m_pTableManager` 表管理器 `ARK_SHARE_PTR` +- `m_pContainerManager` 容器管理器 `ARK_SHARE_PTR` +- `m_pEventManager` 事件管理器 `ARK_SHARE_PTR` + +其中用到的几个类如下 + +- `AFNodeManager` 属性管理类 用来管理对象的属性 + + ```cpp + using DataList = AFMap; + + // class meta + ARK_SHARE_PTR class_meta_{nullptr}; + + // call back + NODE_COMPONENT_FUNCTOR func_; + + // data list + DataList data_list_; + ``` + +- `AFTableManager` 表管理类 用来管理表 包括创建查找等操作 + + ```cpp + using TableList = AFMap; + + // class meta + ARK_SHARE_PTR class_meta_{nullptr}; + + // table list + TableList table_list_; + ``` + +- `AFIContainerManager` 容器管理接口类 对应`AFCContainerManager` 用来管理容器 包括创建查找等操作 + + ```cpp + // container + using ContainerList = AFSmartPtrMap; + ContainerList container_data_; + ``` + +- `AFIContainer` 容器接口类 对应`AFCContainer` 用于复杂结构 可以存放其它子对象 + + ```cpp + using EntityDataList = AFSmartPtrMap; + + // contain entity class meta + ARK_SHARE_PTR container_meta_{nullptr}; + + // index start + uint32_t current_index_{0u}; + + // parent id + AFGUID parent_{NULL_GUID}; + + // entity data + EntityDataList entity_data_list_; + ``` + +- `AFIEventManager` 事件管理类 处理对象的事件 + +- `AFINode` 属性接口类 对应`AFCNodeTypeName`(`TypeName`是基本类型名) 用来存放属性的值和对应的定义 + + ```cpp + // meta + ARK_SHARE_PTR data_meta_{nullptr}; + + // value + TypeName data_{TypeName()}; + ``` + +- `AFITable` 表接口类 对应`AFCTable` + + ```cpp + using TableData = AFMap; + + // object unique guid + AFGUID guid_{NULL_GUID}; + + // table meta + ARK_SHARE_PTR table_meta_{nullptr}; + + // current row + uint32_t current_row{0u}; + + // table data + TableData data_; + ``` + +- `AFIRow` 表行接口类 对应`AFCRow` + + ```cpp + // row + uint32_t row_{0u}; + + // data + ARK_SHARE_PTR m_pNodeManager{nullptr}; + ``` + +### 结构图 + +![data structure](../_images/data-structure.png) \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/directory-structure.md b/docs/site/legacy-source/en-us/directory-structure.md new file mode 100644 index 000000000..df2827801 --- /dev/null +++ b/docs/site/legacy-source/en-us/directory-structure.md @@ -0,0 +1,53 @@ +# Directory structure + +> [!NOTE] +> ARK directory sturcture + +``` +|-- bin #binary dir +| |-- bin #excutable files dir +| |-- binlog #log dir +| |-- bus_conf #bus config dir +| |-- lib #plugin and 3rd dynamic libraries dir +| |-- plugin_conf #plugin config dir +| |-- resource #designer +| | |-- client #csv files for client +| | |-- excel #excel files for designer +| | |-- mysql #mysql schema for db +| | |-- proto #name file that be generated by tools +| | |-- res #xml files that be generated from excel files by tools +| | |-- schema #schema files thet be generated from excel files by tools +| | |-- script #lua script(for now, not used) +| |-- tools #transfer excels to xmls +|-- cmake #3rd cmake dependencies +|-- dep #3rd libraries +| |-- args #parse command line arguments +| |-- common #some OS mini hpp files +| |-- rapidxml #operate xml files +| |-- spdlog #log library +|-- frame #source code +| |-- app #the executor which launch plugins +| |-- base #some common header files +| |-- interface #interface files +| |-- proto #self protocol files +| |-- samples #samples +| |-- sdk #general plugins and base libs +| | |-- bus #bus plugin +| | |-- kernel #Kernel plugin, include Entity management and data management, very important +| | |-- net #Network plugin, supply TCP http websock server and client +| | |-- utility #some useful module, like guid, log, etc. +| |-- server #server plugins +| | |-- db #database proxy plugin +| | |-- dir #directory plugin +| | |-- game #game plugin, main game logic +| | |-- login #login plugin +| | |-- log #remote log plugin +| | |-- master #master plugin, manage all other processes +| | |-- oss #operating support system plugin, just for game operators +| | |-- proxy #net traffic bridge for client and server-side +| | |-- router #transfer net traffic to right processes +| | |-- world #world plugin, manage zone processes, like game, proxy, login, etc. +| |-- tools #tools for this project +| |-- excel2xml #transfer excel files to xml +|-- plugins #3rd plugins, like mysql, redis, etc. +``` \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/faq.md b/docs/site/legacy-source/en-us/faq.md new file mode 100644 index 000000000..32cce9075 --- /dev/null +++ b/docs/site/legacy-source/en-us/faq.md @@ -0,0 +1 @@ +# FAQ \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/kernel-plugin.md b/docs/site/legacy-source/en-us/kernel-plugin.md new file mode 100644 index 000000000..fdc74e17e --- /dev/null +++ b/docs/site/legacy-source/en-us/kernel-plugin.md @@ -0,0 +1,148 @@ +# KernelPlugin介绍 + +该插件是`ARK框架`中的核心插件, 主要用来管理Entity对象和进程配置数据, 其中主要包含四个模块, + +- AFCMetaClassModule +- AFCConfigModule +- AFCMapModule +- AFCKernelModule + +该四个插件对应的功能各不相同, 却各有关联，下面详细讲解各个模块的功能. + +## AFCMetaClassModule + +主要负责ARK中`MetaClass`的管理, 这里的`MetaClass`类似`Entity`, 区别于`Entity`的是, `MetaClass`是通过`配置`出来的, 而`Entity`是在运行过程中`动态创建`出来的, 其余功能和`Entity`类似. +`MetaClassModule`通过加载`DataConfig/Struct/LogicClass.xml`来获得ClassName, InstancePath(Class的结构文件路径), ResPath(Class的配置文件路径). 有些动态创建出来的`Entity`需要通过`MetaClass`来提供结构样式, 这种`Class`的Res文件是没有配置的, 因为都是动态创建过程中赋值. 同时也提供`ClassEvent`和`ClassCallback`, 当该`MetaClass`对应的`Entity`创建时, 可以对应处理事件. + +下面举例说明如何使用ClassCallback + +```cpp +bool AFCPropertyModule::PostInit() +{ + m_pKernelModule = pPluginManager->FindModule(); + m_pElementModule = pPluginManager->FindModule(); + m_pClassModule = pPluginManager->FindModule(); + m_pPropertyConfigModule = pPluginManager->FindModule(); + m_pLevelModule = pPluginManager->FindModule(); + + //创建Player的ClassCallback + //根据模块可以自由添加, 一个Class可以有多个ClassCallback + m_pKernelModule->AddClassCallBack(ARK::Player::ThisName(), this, &AFCPropertyModule::OnObjectClassEvent); + + return true; +} +``` + +而AFCPropertyModule::OnObjectClassEvent中可以根据`ClassEvent`处理不同的业务逻辑，做到解耦(*注意:AddClassCallBack要在该Class对应的Entity创建前调用*) + +## AFCConfigModule + +主要管理配置类数据, 通过上面的`MetaClassModule`获得Instance和ResPath后，对这两个分别加载进内存，形成配置文件，后续就可以通过下面接口获取配置内容了 + +```cpp +bool ExistConfig(const std::string& config_id) override; +bool ExistConfig(const std::string& class_name, const std::string& config_id) override; + +bool GetNodeBool(const std::string& config_id, const std::string& node_name) override; +int32_t GetNodeInt(const std::string& config_id, const std::string& node_name) override; +int64_t GetNodeInt64(const std::string& config_id, const std::string& node_name) override; +float GetNodeFloat(const std::string& config_id, const std::string& node_name) override; +double GetNodeDouble(const std::string& config_id, const std::string& node_name) override; +const char* GetNodeString(const std::string& config_id, const std::string& node_name) override; +``` + +## AFCMapModule + +用来创建场景和管理场景中的Entity列表(*为了更加灵活, 当前是按照地图全图广播的, 如有RPG项目的需求，请自行添加RPG中的九宫格/十字链表等视野管理*), 可以获取场景中的Entity数据, 从而进行数据广播等等. +*因暂时ARK框架中并无实际逻辑，所以此模块暂时并没有特别多的用处.* + +## AFCKernelModule + +主要用来作为Entity数据管理, 是本插件的核心模块，几乎所有的接口都是来自此模块, 主要用途为获取Entity对象, 获取/修改`Entity`的`Node`和`Table`数据, 同时可以注册公共的`ClassEvent`, `DataNodeEvent`, `DataTableEvent`(公共事件并不局限于某个Class/Entity) + +公共注册接口如下: + +```cpp +template +bool RegCommonClassEvent(BaseType* pBase, int (BaseType::*handler)(const AFGUID&, const std::string&, const ARK_ENTITY_EVENT, const AFIDataList&)) +{ + CLASS_EVENT_FUNCTOR functor = std::bind(handler, pBase, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4); + return RegCommonClassEvent(std::make_shared(functor)); +} + +template +bool RegCommonDataNodeEvent(BaseType* pBase, int (BaseType::*handler)(const AFGUID&, const std::string&, const AFIData&, const AFIData&)) +{ + DATA_NODE_EVENT_FUNCTOR functor = std::bind(handler, pBase, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4); + return RegCommonDataNodeEvent(std::make_shared(functor)); +} + +template +bool RegCommonDataTableEvent(BaseType* pBase, int (BaseType::*handler)(const AFGUID&, const DATA_TABLE_EVENT_DATA&, const AFIData&, const AFIData&)) +{ + DATA_TABLE_EVENT_FUNCTOR functor = std::bind(handler, pBase, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4); + return RegCommonDataTableEvent(std::make_shared(functor)); +} +``` + +数据获取接口如下: + +```cpp +virtual ARK_SHARE_PTR GetEntity(const AFGUID& ident) = 0; +virtual ARK_SHARE_PTR CreateEntity(const AFGUID& self, const int nSceneID, const int nGroupID, const std::string& strClassName, const std::string& strConfigIndex, const AFIDataList& arg) = 0; + + +virtual bool FindNode(const AFGUID& self, const std::string& name) = 0; + +virtual bool SetNodeBool(const AFGUID& self, const std::string& name, const bool value) = 0; +virtual bool SetNodeInt(const AFGUID& self, const std::string& name, const int32_t value) = 0; +virtual bool SetNodeInt64(const AFGUID& self, const std::string& name, const int64_t value) = 0; +virtual bool SetNodeFloat(const AFGUID& self, const std::string& name, const float value) = 0; +virtual bool SetNodeDouble(const AFGUID& self, const std::string& name, const double value) = 0; +virtual bool SetNodeString(const AFGUID& self, const std::string& name, const std::string& value) = 0; +virtual bool SetNodeObject(const AFGUID& self, const std::string& name, const AFGUID& value) = 0; + +virtual bool GetNodeBool(const AFGUID& self, const std::string& name) = 0; +virtual int32_t GetNodeInt(const AFGUID& self, const std::string& name) = 0; +virtual int64_t GetNodeInt64(const AFGUID& self, const std::string& name) = 0; +virtual float GetNodeFloat(const AFGUID& self, const std::string& name) = 0; +virtual double GetNodeDouble(const AFGUID& self, const std::string& name) = 0; +virtual const char* GetNodeString(const AFGUID& self, const std::string& name) = 0; +virtual const AFGUID GetNodeObject(const AFGUID& self, const std::string& name) = 0; +////////////////////////////////////////////////////////////////////////// +virtual AFDataTable* FindTable(const AFGUID& self, const std::string& name) = 0; +virtual bool ClearTable(const AFGUID& self, const std::string& name) = 0; + +virtual bool SetTableBool(const AFGUID& self, const std::string& name, const int row, const int col, const bool value) = 0; +virtual bool SetTableInt(const AFGUID& self, const std::string& name, const int row, const int col, const int32_t value) = 0; +virtual bool SetTableInt64(const AFGUID& self, const std::string& name, const int row, const int col, const int64_t value) = 0; +virtual bool SetTableFloat(const AFGUID& self, const std::string& name, const int row, const int col, const float value) = 0; +virtual bool SetTableDouble(const AFGUID& self, const std::string& name, const int row, const int col, const double value) = 0; +virtual bool SetTableString(const AFGUID& self, const std::string& name, const int row, const int col, const std::string& value) = 0; +virtual bool SetTableObject(const AFGUID& self, const std::string& name, const int row, const int col, const AFGUID& value) = 0; + +virtual bool GetTableBool(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual int32_t GetTableInt(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual int64_t GetTableInt64(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual float GetTableFloat(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual double GetTableDouble(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual const char* GetTableString(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual const AFGUID GetTableObject(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +``` + +举个数据获取的例子: + +```cpp +int AFCLevelModule::AddExp(const AFGUID& self, const int nExp) +{ + //通过DataNode名称获取ID为self的Entity数据 + int eJobType = m_pKernelModule->GetNodeInt(self, ARK::Player::Job()); + int nCurExp = m_pKernelModule->GetNodeInt(self, ARK::Player::EXP()); + int nLevel = m_pKernelModule->GetNodeInt(self, ARK::Player::Level()); + int nMaxExp = m_pPropertyConfigModule->CalculateBaseValue(eJobType, nLevel, ARK::Player::MAXEXP()); + + //Do something + + return 0; +} +``` \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/net-plugin.md b/docs/site/legacy-source/en-us/net-plugin.md new file mode 100644 index 000000000..1fc1ac081 --- /dev/null +++ b/docs/site/legacy-source/en-us/net-plugin.md @@ -0,0 +1 @@ +# Net plugin \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/plan.md b/docs/site/legacy-source/en-us/plan.md new file mode 100644 index 000000000..dcf35712d --- /dev/null +++ b/docs/site/legacy-source/en-us/plan.md @@ -0,0 +1,58 @@ +# Plan + +## High priority + +- [ ] excel格式修改为一张excel里放所有的schema,其他配置表分开来写,兼容现在的格式 +- [x] 调整代码风格统一 +- [ ] 修改进程启动优先链接logserver，如果logserver连不上，则直接不能启动，这样就可以从一开始就能打log了 +- [x] spdlog升级 +- [ ] 增加dirty data layer, 当一个客户端请求处理完成后统一下发变化数据，不能有变有发，会导致小包太碎，并且浪费协议的head +- [ ] 文档逐步补齐，概念介绍、设计理念、服务器架构、使用例子 +- [x] 所有的基础数据结构向C++容器看齐 +- [ ] 服务中心注册(考虑etcd/consul来做) +- [ ] 定时log和心跳改为timer方式，不要再是用update和HeartBeat了 +- [ ] 修改配置打包工具(用Excel编辑，生成`csv`来给工程读取。为解决多人协作冲突, excel可以用名字后缀区分，类如Item.A.xlsx Item.B.xlsx) +- [ ] ~~插件加载顺序(通过配置中的字段, 或者通过配置的顺序)~~ +- [x] 修改xml不再直接用rapidxml，用封装后的AFXml +- [x] 接口类重新设计纯粹化 +- [ ] 增加生成器来生成重复代码(_插件类和模块类_) + +## Low priority + +- [ ] Map, Layer,对应修改协议和Client的处理(**概念已经修改, 还未对接客户端**) +- [ ] 关于背包类的table，整理或者交换，需要改成别的方式 +- [ ] 优化数据同步的流量,减小属性同步的体积(去掉`NodeName`和`TableName`类似的string同步, 上线先同步index和name的映射，后续全部用index下发，入库用name) +- [ ] 拓展DataTable的组成，例如道具包含了宝石(带经验，附魔等)、武器(带随机属性)等东西，DataTable现有的二维结构是特定的，不方便做扩展 +- [ ] 增加网络库和性能的基准测试用例，放到目录benchmark/unittest +- [ ] 增加kcp +- [ ] 脚本模块使用SWIG +- [ ] 考虑使用ECS，全部对象Entity化，通过GUID来确定属于哪个分组的哪个位置，能快速定位和查找(通过守望先锋、ET、[ECS-unity](https://github.com/sschmid/Entitas-CSharp)，具体还要再调研) +- [ ] 增加coroutine，参考libgo +- [ ] 引入tcmalloc +- [ ] 增加监控web页面(vue-admin) +- [ ] 增加Deployment web工具 +- [ ] 增加消息队列处理 +- [ ] 增加运维工具(tcm & deploy) +- [ ] 部分计算密集的地方使用多线程 + +## Part finished + +- [x] spdlog增加按照文件夹/大小/小时滚动的sink(*已经修改了一部分，还需要进一步修改成tlog的格式，/data/binlog/1001/20180627/game1_hour.log*) +- [x] 增加consistent_hash_map(**已增加, 还未启用**) + +## Finished + +- [x] 新架构修改 +- [x] 增加连接关系的配置，不再通过程序中手动设置关系(bus_relation, server_settting, IP和port不用再指定了, 通过获取IP和动态生成port), 网络地址修改为tcp://0.0.0.0:9001 wss://0.0.0.0:9001这样的URL +- [x] 修改bin文件夹debug和release在一起，debug和release分开配置(方便配置是一套) +- [x] guid改为内部指针类型(降低其他非guid类型的内存占用)***修改为int64_t了,不需要再考虑内存占用了*** +- [x] 增加网络插件,这样可以将网络模块和业务逻辑模块拆分开(现在NetClient和NetServer还是跟业务关联太紧密了) +- [x] net plugin增加endpoint +- [x] kernel和config插件还是得合并为一个，因为kernel非常依赖config插件 + +## Bugs + +- [ ] ClearRow的时候后面的行号会变化，所以要考虑要么行号不变，只是置空，要么就得客户端来根据DeleteRow消息同步修改后续的row变化 +- [x] 现在的ConfigPlugin数据加载有问题 +- [x] AFMapEx的First Next返回值有问题 + \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/quick-start.md b/docs/site/legacy-source/en-us/quick-start.md new file mode 100644 index 000000000..46e1cbce4 --- /dev/null +++ b/docs/site/legacy-source/en-us/quick-start.md @@ -0,0 +1,103 @@ +# Quick start + +## Get the Sources + +git clone https://github.com/ArkGame/ARK.git + +or + +svn checkout https://github.com/ArkGame/ARK + +## Dependencies + +| Library | Version | License | +| ----------------------------------------------------- | ------- | --------------------------------------------------------------------------------- | +| [brynet](https://github.com/IronsDu/brynet) | master | [MIT](https://github.com/IronsDu/brynet/blob/master/LICENSE) | +| [spdlog](https://github.com/gabime/spdlog) | 0.17.0 | [MIT](https://github.com/gabime/spdlog/blob/v1.x/LICENSE) | +| [google protobuf](https://github.com/google/protobuf) | 3.5.x | [Google License](https://github.com/protocolbuffers/protobuf/blob/master/LICENSE) | +| [args](https://github.com/Taywee/args) | 6.2.0 | [MIT](https://github.com/Taywee/args/blob/master/LICENSE) | +| [rapidxml](https://github.com/ArkNX/rapidxml) | 1.13 | [LICENSE](http://rapidxml.sourceforge.net/license.txt) | + +## Supported Compilers + +- GCC 4.9+ (**Recommend. Tested in Ubuntu 15.04**) +- MSVC VS2017+ (**Recommend VS2019. Tested in Win7/10**) + +## Build and Launch + +### Windows + +##### Prerequisites + +- Windows 7 or later +- Visual Studio 2017 +- Git +- CMake + +##### Step + +Using CMake + +1. Clone the source files +2. Run command line + + ```batch + cd path/to/ARK + git submodule update --init + md build + cd build + cmake -G "Visual Studio 16" -A x64 .. + ``` + +3. Start and build `ark.sln` +4. Run `ARK/bin/tools/gen-config.bat` to generate configuration files +> [!WARNING] +> Need python3 environment.The 3rd dependencies in `ARK/bin/tools/config_tool/README.md`. +5. Install the [Consul](https://consul.io), run the command below, + ```bash + cd path/to/consul + consul.exe agent -server -ui -bootstrap-expect=1 -data-dir=./ -node=ark_consul_service -client=0.0.0.0 -bind=127.0.0.1 -log-file=./log/ -datacenter=ARK + ``` +6. Run the binary file by `bin/rund.bat` + +> [!NOTE] +> If you are using other Visual Studio version, please use `cmake -G "Visual Studio 15 Win64" ..` with the right Visual Studio version.
+ +### linux + +##### Prerequisites + +- g++ 4.9+ (need C++ 11 and std::regex) +- Git +- CMake 3.0+ +- libtool +- automake + +Using CMake + +1. Clone the source file. +2. Run the command, + + ```shell + cd path/to/ARK + git submodule update --init + mkdir -p build/debug && cd build/debug + cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=debug ../.. + make + ``` + +> [!NOTE] +> If you need build release version, please add `-DCMAKE_BUILD_TYPE=release` in cmake command.
+To accelerate the building speed, you can use `make -j [num]` to run multiple complication jobs simultaneously. However, that may exhaust the memory. + +3. Run `path/to/ARK/bin/tools/gen-config.sh` to generate configuration files + +> [!WARNING] +> Need Python3 environment.The 3rd dependencies in `ARK/bin/tools/config_tool/README.md`. + +4. Install the [Consul](https://consul.io), run the command below, + ```bash + cd path/to/consul + ./consul agent -server -ui -bootstrap-expect=1 -data-dir=./ -node=ark_consul_service -client=0.0.0.0 -bind=127.0.0.1 -log-file=./log/ -datacenter=ARK + ``` +5. Run the binary file by `bin/rund.sh` diff --git a/docs/site/legacy-source/en-us/server-architecture.md b/docs/site/legacy-source/en-us/server-architecture.md new file mode 100644 index 000000000..d2b7a37e2 --- /dev/null +++ b/docs/site/legacy-source/en-us/server-architecture.md @@ -0,0 +1 @@ +# Server architecture \ No newline at end of file diff --git a/docs/site/legacy-source/en-us/tools.md b/docs/site/legacy-source/en-us/tools.md new file mode 100644 index 000000000..537d60c60 --- /dev/null +++ b/docs/site/legacy-source/en-us/tools.md @@ -0,0 +1 @@ +# Tools \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/app-architecture.md b/docs/site/legacy-source/zh-cn/app-architecture.md new file mode 100644 index 000000000..7858f1348 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/app-architecture.md @@ -0,0 +1,11 @@ +# 应用架构介绍 + +ARK中一个应用(application)是由插件(plugin)组成的, 插件(plugin)由很多模块(module)组成的, module通过面向接口编程(IOP)来做到功能调用. + +这样做的好处有很多, 解耦、热插拔、模块独立、开发者关注更少、单一原则等等。 + +下图是ARk中应用的组成示例: + +![app-architecture](../_images/app-architecture.png) + +其中不同插件提供不同的功能, KernelPlugin主要来管理和驱动Entity实例的数据, 详情见[KernelPlugin介绍](/zh-cn/kernel-plugin.md). \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/app.md b/docs/site/legacy-source/zh-cn/app.md new file mode 100644 index 000000000..c9123ad7e --- /dev/null +++ b/docs/site/legacy-source/zh-cn/app.md @@ -0,0 +1 @@ +# 插件运行工具 \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/benchmark.md b/docs/site/legacy-source/zh-cn/benchmark.md new file mode 100644 index 000000000..c5ee18b6d --- /dev/null +++ b/docs/site/legacy-source/zh-cn/benchmark.md @@ -0,0 +1 @@ +# 压力测试报告 \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/bus-plugin.md b/docs/site/legacy-source/zh-cn/bus-plugin.md new file mode 100644 index 000000000..2d0f51801 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/bus-plugin.md @@ -0,0 +1 @@ +# Bus插件 \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/changelog.md b/docs/site/legacy-source/zh-cn/changelog.md new file mode 100644 index 000000000..ddbb515b0 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/changelog.md @@ -0,0 +1,88 @@ +# Changelogs + +### version 0.9 + +- Fix `HeartBeatManager` remove mistake(Thanks @sks) +- Add `DateTime` +- Fix sonar bad smells +- Replace `AFBitValue` with `std::bitset` +- Add `random` functions +- Replace `easylogging++` with `spdlog` +- Add BusPlugin(use `busid` as server id and communicate, for now not totally finished) +- Update `Proto` library to `ProtoPlugin` +- Update `Net` library to `NetPlugin` +- Update `brynet` to the newest version +- Refactoring the net plugin +- Add DataTable callback when `DataTable.Add/Set/Del(data)` +- Modify table row index +- Modify module register order and fix config's bug +- Optimise - Don't load DataNode in AFConfigModule when the node value is the default +- Add AFCMsgModule(not finished yet) + +### version 0.8 + +- Replace `evpp` with `brynet` for reducing dependence +- Add `AFCronScheduleModule`, using `cron` syntax +- Add `WebSocket` support +- Replace `easylogging++` with `spdlog` +- Add `SonarCloud` check +- Add `Codecov` test +- Fix some warnings +- Fix some code smells of SonarCloud +- Fix GUID bug +- Fix some known bugs + +### version 0.7 + +- Restructure log module +- Update to VS2017 as default IDE in windows +- Add function `strlcpy` +- Use a new memory pool +- Fix `AFTimer` bugs +- Reduce `.git` disk usage +- Fix Net bugs +- Fix parameters warnings +- Fix tools, config id can be a number +- Rename Example files + +### version 0.6 + +- Change Mem allocation +- Add Timer Module(Using time wheel) +- Modify Plugin DLL entry and exit functions by using macro `ARK_DLL_PLUGIN_ENTRY(Plugin Class)` +- Add `ARK_STATIC_ASSERT` +- Add launch parameters for launching multi-processes +- Use `std::is_base_of` to instead self derived class check + +### version 0.5 + +- Fix some memory bugs +- Add memory pool and allocation +- Add wiki(Unfinished) +- Restructure file directories +- Add a new file processing tool + +### version 0.4 + +- Unified concept, Property -> DataNode Record -> DataTable +- Unified configurations +- Update Google.Protobuffer 3.x +- Fix some bugs + +### version 0.3 + +- Fix msg head bugs +- Rename some files + +### version 0.2 + +- Modify base data structure +- Modify the performance of the network +- Modify directories structure +- Add CMake support(Linux platform is testing) +- Modify the compiling way of **Dep** +- Modify GUID to 128 bits + +### version 0.1 + +- First release \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/coding-guide.md b/docs/site/legacy-source/zh-cn/coding-guide.md new file mode 100644 index 000000000..00e33d104 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/coding-guide.md @@ -0,0 +1,27 @@ +# 代码规范 + +- 所有的代码都在`ark命名空间` +- 所有接口类都需以`AFI`开始, 所有的实现类都需要以`AFC`开始, 例如: `AFITestModule`, `AFCTestModule` +- 文件名命名要与本文件中的类名一致 +- `局部变量`和`参数`都使用小写字母,单词之间使用`_`连接 如:`arg_list` +- `成员变量`和`全局变量`使用`小写字母`, 使用`_`结尾, 单词之间使用`_`连接 如:`member_a_` +- 服务器使用的基础`枚举`变量在`src/base/AFEnum.hpp`中定义, 业务内的枚举请自行定义 +- `宏`定义使用`大写字母`, 单词之间使用`_`连接 如:`ARK_TO_STRING` +- 函数设计尽量保证逻辑`功能单一`, 只做一件事情 +- 函数尽量`不要超过100行`, 超过请将部分代码重构`封装`成函数调用 +- `成员变量`和`成员函数`声明前都需要加上`注释` +- `局部变量`按就近原则声明, 在哪里使用就在哪里声明 最好不要在函数头申明然后在函数尾使用这类情况 +- 使用`指针`之前, 不能确保其有效之前必须要加上`判断` +- `堆`上申请的`内存`一定要`释放`, 防止内存泄漏 +- `接口`尽量使用意义清楚 +- 尽量使用11标准后的关键字,例如`final` `override` +- 不要使用中文注释 +- 注释风格 + ```cpp + /// only one line comment + + /** + * multi line comment + * another comment + */ + ``` \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/concept.md b/docs/site/legacy-source/zh-cn/concept.md new file mode 100644 index 000000000..6d8cac0e6 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/concept.md @@ -0,0 +1,41 @@ +# Concepts + +## Module(模块) + +表示一类逻辑业务的合集, 相对来说功能比较集中, 可以做到低耦合, 并且可以通过`IOP`(面向接口编程)的方式来给其他模块提供耦合功能.例如LogModule等. + +## Plugin(插件) + +表示一系列Module的集合, 按照更大的业务来分类, 例如GameLogic插件, Navimesh插件等. + +## Application(应用) + +表示一个独立的完整功能的进程, 可以包含大量插件, 例如GameServer等. + +## DataNode + +表示一维数据, 通常用来表示Entity附带的任意一维数据结构, 当前可以为常用内置数据类型(`bool` `int` `int64` `double` `float` `string` `GUID`). 例如`PlayerEnity`附带的HP MP等数据. + +## DataTable + +表示二维数据, 通常用来表示Entity附带的任意二维数据结构,结构与Microsoft Excel的二维结构类似, 包含`Row`和`Column`, 并且结构可以通过Excel动态传入, Table中任意Cell可以为常用内置数据类型(`bool` `int` `int64` `double` `float` `string` `GUID`). 例如`PlayerEnity`附带的`ItemTable`. + +## Entity(实体) + +表示游戏内动态创建的任意实体对象, 该实体对象通常携带大量`DataNode`和`DataTable`, 例如：PlayerEntity、MonsterEntity、NPCEntity等. + +## App工具 + +用来加载多个Plugin动态链接库, 从而形成一个Application. + +## GUID + +表示游戏内唯一ID, 并且全区全服不重复, 可以用来做`EntityID`等游戏内有唯一性需求的ID. + +## Event(事件) + +游戏逻辑监听和产生事件, 用来解耦游戏逻辑. + +## Google Proto-buffer + +Google开源的跨平台, 跨语言的数据序列化库, 详见https://github.com/google/protobuf \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/create-new-module.md b/docs/site/legacy-source/zh-cn/create-new-module.md new file mode 100644 index 000000000..74a045ddb --- /dev/null +++ b/docs/site/legacy-source/zh-cn/create-new-module.md @@ -0,0 +1,115 @@ +# 快速开发一个新模块 + +## 一个简单模块的搭建 + +```cpp +#pragma once + +#include "base/AFPluginManager.hpp" +#include "interface/AFIPlugin.hpp" +#include "interface/AFIModule.hpp" +#include "utility/interface/AFITimerModule.hpp" +#include "log/interface/AFILogModule.hpp" +#include "utility/interface/AFIScheduleModule.hpp" +#include "utility/interface/AFIGUIDModule.hpp" + +namespace ark { + +class Sample1Module final : public AFIModule +{ + ARK_DECLARE_MODULE_FUNCTIONS +public: + bool Init() override; + bool PostInit() override; + bool Update() override; + bool PreShut() override; + bool Shut() override; + +protected: + AFITimerModule* m_pTimerModule; + AFILogModule* m_pLogModule; + AFIGUIDModule* m_pGUIDModule; + AFIScheduleModule* m_pScheduleModule; +}; + +} // namespace ark +``` + +说明: + +- 所有的模块都继承自AFIModule +- 模块类中包含几个常规的状态机执行函数(稍后详细讲解) +- 模块类的成员变量除过自己逻辑功能的变量外, 主要成员变量为其他模块指针, 用来调用其他模块的功能(请自行搜索**面向接口编程IOP**) + +## 模块执行状态机 + +前文提到, 我们所有的模块都继承自`AFIModule`, AFIModule中主要包含了如下几个插件在不同状态下执行的虚函数, 如下 + +```cpp +#pragma once + +#include "base/AFPlatform.hpp" +#include "base/AFMacros.hpp" + +namespace ark { + +class AFPluginManager; + +class AFIModule +{ +public: + AFIModule() = default; + virtual ~AFIModule() = default; + + virtual bool Init() { return true; } + virtual bool PostInit() { return true; } + virtual bool CheckConfig() { return true; } + virtual bool PreUpdate() { return true; } + virtual bool Update() { return true; } + virtual bool PreShut() { return true; } + virtual bool Shut() { return true; } + + virtual AFPluginManager* GetPluginManager() const { return nullptr; } + + virtual void SetPluginManager(AFPluginManager* p) + { + // Do nothing in the module interface + } + + virtual const std::string& GetName() const + { + static const std::string null_str = ""; + return null_str; + } + + virtual void SetName(const std::string& value) + { + // Do nothing in the module interface + } +}; + +} // namespace ark +``` + +模块执行流程图: + +```plantuml +@startuml + +start + :Init; + :PostInit; + :CheckConfig; + :PreUpdate; + +while (Check exit?) is (no) + :Update; +endwhile(yes) + + :PreShut; + :Shut; + +stop + +@enduml +``` \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/create-new-plugin.md b/docs/site/legacy-source/zh-cn/create-new-plugin.md new file mode 100644 index 000000000..9032179f0 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/create-new-plugin.md @@ -0,0 +1,50 @@ +# 快速开发一个新插件 + +## 一个简单插件的搭建 + +头文件 + +```cpp +#pragma once + +#include "interface/AFIPlugin.hpp" +#include "base/AFPluginManager.hpp" + +namespace ark { + +ARK_DECLARE_PLUGIN(Sample1Plugin) + +} // namespace ark +``` + +源文件 + +```cpp +#include "Sample1Plugin.h" +#include "Sample1Module.h" + +namespace ark { + +ARK_DECLARE_PLUGIN_DLL_FUNCTION(Sample1Plugin) + +void Sample1Plugin::Install() +{ + ARK_REGISTER_MODULE(Sample1Module, Sample1Module); +} + +void Sample1Plugin::Uninstall() +{ + ARK_DEREGISTER_MODULE(Sample1Module, Sample1Module); +} + +} // namespace ark +``` + +## 插件流程说明 + +插件安装`Install`, 将插件内的模块通过`ARK_REGISTER_MODULE`一个个注册到插件内. +插件卸载`Uninstall`, 将插件内的模块通过`ARK_DEREGISTER_MODULE`一个个从插件内卸载. + +> [!ATTENTION] +> 注意: 这里模块`module`注册和卸载中的两个类名, 前面为`接口(Interface)类`, 后面为`实现(Concrete)类`. +> 文中具体的宏的实现请在项目代码中查看。 \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/data-driven.md b/docs/site/legacy-source/zh-cn/data-driven.md new file mode 100644 index 000000000..8556b76a1 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/data-driven.md @@ -0,0 +1 @@ +# 数据驱动 \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/data-structure.md b/docs/site/legacy-source/zh-cn/data-structure.md new file mode 100644 index 000000000..95e8af879 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/data-structure.md @@ -0,0 +1,162 @@ +# 数据结构说明 + +`ARK` 使用数据和定义分离的策略 数据定义包含名字 其对应的下标 类型和是否存储等特征 数据实体包含一个指向对应定义的指针和具体的值 对象中属性用数据的下标和值的映射存储 + +## 数据配置生成 + +`ARK` 通过`bin/tools`文件夹下的工具`gen-config`把`bin/resource/excel`下的文件生成对应的数据定义文件和配置文件 分别放在`bin/resource/meta`和`bin/resource/server` 并且在`bin/resource/code`生成类的属性名和下标的接口 + +### 数据定义 + +有四个数据定义类 + +1. `AFNodeMeta` 对象的属性定义 + +- `name_` 属性名 `string` +- `type_` 类型 `enum class ArkDataType` +- `index_` 下标 `uint32` +- `mask_` 是否存储同步等特性 `std::bitset` + +2. `AFTableMeta` 表结构定义 + +- `name_` 表名 `string` +- `index_` 下标 `uint32` +- `type_name_` 表对应的`AFClassMeta` 名称 `string` +- `class_meta_` 对应的`AFClassMeta` `ARK_SHARE_PTR` +- `mask_` 是否存储同步等特性 `std::bitset` + +3. `AFContainerMeta` 容器定义(用来存放对象 借以实现复杂数据结构) + +- `name_` 容器名 `string` +- `index_` 下标 `uint32` +- `class_name_` 容器容纳的对象名 `string` + +4. `AFClassMeta` 类结构定义 + +- `name_` 类名 `string` +- `res_path_` 资源路径 string +- `name_index_list_` 字段名和下表映射 `map` +- `data_meta_list_` 属性映射 `map` +- `table_meta_list_` 表映射 `map` +- `container_meta_list_` 容器映射 `map` +- `class_meta_call_back_` 函数回调 `pointer` + +### 数据实体 + +数据实体有两个 + +1. `AFCStaticEntity` 配置数据实体类 对应接口类`AFIStaticEntity ` + +- `config_id_` 配置id `int` (因为配置id通用且需频繁访问 所以单独列出以提高访问效率) +- `m_pNodeManager` 属性管理器 `ARK_SHARE_PTR` + +2. `AFCEntity ` 对象实体类 对应接口类`AFIEntity ` + +- `guid_` 唯一编号 `AFGUID` +- `config_id_` 配置id `int` +- `parent_container_` 所属容器指针 `ARK_SHARE_PTR` +- `map_entity_id_` 地图实体id `int` +- `custom_data_list_` 自定义属性 `hashmap` (可以手动添加和删除属性 无需在文件中先定义好) +- `m_pNodeManager` 属性管理器 `ARK_SHARE_PTR` +- `m_pTableManager` 表管理器 `ARK_SHARE_PTR` +- `m_pContainerManager` 容器管理器 `ARK_SHARE_PTR` +- `m_pEventManager` 事件管理器 `ARK_SHARE_PTR` + +其中用到的几个类如下 + +- `AFNodeManager` 属性管理类 用来管理对象的属性 + + ```cpp + using DataList = AFMap; + + // class meta + ARK_SHARE_PTR class_meta_{nullptr}; + + // call back + NODE_COMPONENT_FUNCTOR func_; + + // data list + DataList data_list_; + ``` + +- `AFTableManager` 表管理类 用来管理表 包括创建查找等操作 + + ```cpp + using TableList = AFMap; + + // class meta + ARK_SHARE_PTR class_meta_{nullptr}; + + // table list + TableList table_list_; + ``` + +- `AFIContainerManager` 容器管理接口类 对应`AFCContainerManager` 用来管理容器 包括创建查找等操作 + + ```cpp + // container + using ContainerList = AFSmartPtrMap; + ContainerList container_data_; + ``` + +- `AFIContainer` 容器接口类 对应`AFCContainer` 用于复杂结构 可以存放其它子对象 + + ```cpp + using EntityDataList = AFSmartPtrMap; + + // contain entity class meta + ARK_SHARE_PTR container_meta_{nullptr}; + + // index start + uint32_t current_index_{0u}; + + // parent id + AFGUID parent_{NULL_GUID}; + + // entity data + EntityDataList entity_data_list_; + ``` + +- `AFIEventManager` 事件管理类 处理对象的事件 + +- `AFINode` 属性接口类 对应`AFCNodeTypeName`(`TypeName`是基本类型名) 用来存放属性的值和对应的定义 + + ```cpp + // meta + ARK_SHARE_PTR data_meta_{nullptr}; + + // value + TypeName data_{TypeName()}; + ``` + +- `AFITable` 表接口类 对应`AFCTable` + + ```cpp + using TableData = AFMap; + + // object unique guid + AFGUID guid_{NULL_GUID}; + + // table meta + ARK_SHARE_PTR table_meta_{nullptr}; + + // current row + uint32_t current_row{0u}; + + // table data + TableData data_; + ``` + +- `AFIRow` 表行接口类 对应`AFCRow` + + ```cpp + // row + uint32_t row_{0u}; + + // data + ARK_SHARE_PTR m_pNodeManager{nullptr}; + ``` + +### 结构图 + +![data structure](../_images/data-structure.png) \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/directory-structure.md b/docs/site/legacy-source/zh-cn/directory-structure.md new file mode 100644 index 000000000..26638188e --- /dev/null +++ b/docs/site/legacy-source/zh-cn/directory-structure.md @@ -0,0 +1,53 @@ +# 目录结构说明 + +> [!NOTE] +> ARK目录结构 + +``` +|-- bin #binary dir +| |-- bin #excutable files dir +| |-- binlog #log dir +| |-- bus_conf #bus config dir +| |-- lib #plugin and 3rd dynamic libraries dir +| |-- plugin_conf #plugin config dir +| |-- resource #designer +| | |-- client #csv files for client +| | |-- excel #excel files for designer +| | |-- mysql #mysql schema for db +| | |-- proto #name file that be generated by tools +| | |-- res #xml files that be generated from excel files by tools +| | |-- schema #schema files thet be generated from excel files by tools +| | |-- script #lua script(for now, not used) +| |-- tools #transfer excels to xmls +|-- cmake #3rd cmake dependencies +|-- dep #3rd libraries +| |-- args #parse command line arguments +| |-- common #some OS mini hpp files +| |-- rapidxml #operate xml files +| |-- spdlog #log library +|-- frame #source code +| |-- app #the executor which launch plugins +| |-- base #some common header files +| |-- interface #interface files +| |-- proto #self protocol files +| |-- samples #samples +| |-- sdk #general plugins and base libs +| | |-- bus #bus plugin +| | |-- kernel #Kernel plugin, include Entity management and data management, very important +| | |-- net #Network plugin, supply TCP http websock server and client +| | |-- utility #some useful module, like guid, log, etc. +| |-- server #server plugins +| | |-- db #database proxy plugin +| | |-- dir #directory plugin +| | |-- game #game plugin, main game logic +| | |-- login #login plugin +| | |-- log #remote log plugin +| | |-- master #master plugin, manage all other processes +| | |-- oss #operating support system plugin, just for game operators +| | |-- proxy #net traffic bridge for client and server-side +| | |-- router #transfer net traffic to right processes +| | |-- world #world plugin, manage zone processes, like game, proxy, login, etc. +| |-- tools #tools for this project +| |-- excel2xml #transfer excel files to xml +|-- plugins #3rd plugins, like mysql, redis, etc. +``` \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/faq.md b/docs/site/legacy-source/zh-cn/faq.md new file mode 100644 index 000000000..7bcca1e33 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/faq.md @@ -0,0 +1,4 @@ +# 常见问题 + +> [!NOTE] +> 这里整理了经常被提到 或者 有疑惑的问题。 \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/kernel-plugin.md b/docs/site/legacy-source/zh-cn/kernel-plugin.md new file mode 100644 index 000000000..fdc74e17e --- /dev/null +++ b/docs/site/legacy-source/zh-cn/kernel-plugin.md @@ -0,0 +1,148 @@ +# KernelPlugin介绍 + +该插件是`ARK框架`中的核心插件, 主要用来管理Entity对象和进程配置数据, 其中主要包含四个模块, + +- AFCMetaClassModule +- AFCConfigModule +- AFCMapModule +- AFCKernelModule + +该四个插件对应的功能各不相同, 却各有关联，下面详细讲解各个模块的功能. + +## AFCMetaClassModule + +主要负责ARK中`MetaClass`的管理, 这里的`MetaClass`类似`Entity`, 区别于`Entity`的是, `MetaClass`是通过`配置`出来的, 而`Entity`是在运行过程中`动态创建`出来的, 其余功能和`Entity`类似. +`MetaClassModule`通过加载`DataConfig/Struct/LogicClass.xml`来获得ClassName, InstancePath(Class的结构文件路径), ResPath(Class的配置文件路径). 有些动态创建出来的`Entity`需要通过`MetaClass`来提供结构样式, 这种`Class`的Res文件是没有配置的, 因为都是动态创建过程中赋值. 同时也提供`ClassEvent`和`ClassCallback`, 当该`MetaClass`对应的`Entity`创建时, 可以对应处理事件. + +下面举例说明如何使用ClassCallback + +```cpp +bool AFCPropertyModule::PostInit() +{ + m_pKernelModule = pPluginManager->FindModule(); + m_pElementModule = pPluginManager->FindModule(); + m_pClassModule = pPluginManager->FindModule(); + m_pPropertyConfigModule = pPluginManager->FindModule(); + m_pLevelModule = pPluginManager->FindModule(); + + //创建Player的ClassCallback + //根据模块可以自由添加, 一个Class可以有多个ClassCallback + m_pKernelModule->AddClassCallBack(ARK::Player::ThisName(), this, &AFCPropertyModule::OnObjectClassEvent); + + return true; +} +``` + +而AFCPropertyModule::OnObjectClassEvent中可以根据`ClassEvent`处理不同的业务逻辑，做到解耦(*注意:AddClassCallBack要在该Class对应的Entity创建前调用*) + +## AFCConfigModule + +主要管理配置类数据, 通过上面的`MetaClassModule`获得Instance和ResPath后，对这两个分别加载进内存，形成配置文件，后续就可以通过下面接口获取配置内容了 + +```cpp +bool ExistConfig(const std::string& config_id) override; +bool ExistConfig(const std::string& class_name, const std::string& config_id) override; + +bool GetNodeBool(const std::string& config_id, const std::string& node_name) override; +int32_t GetNodeInt(const std::string& config_id, const std::string& node_name) override; +int64_t GetNodeInt64(const std::string& config_id, const std::string& node_name) override; +float GetNodeFloat(const std::string& config_id, const std::string& node_name) override; +double GetNodeDouble(const std::string& config_id, const std::string& node_name) override; +const char* GetNodeString(const std::string& config_id, const std::string& node_name) override; +``` + +## AFCMapModule + +用来创建场景和管理场景中的Entity列表(*为了更加灵活, 当前是按照地图全图广播的, 如有RPG项目的需求，请自行添加RPG中的九宫格/十字链表等视野管理*), 可以获取场景中的Entity数据, 从而进行数据广播等等. +*因暂时ARK框架中并无实际逻辑，所以此模块暂时并没有特别多的用处.* + +## AFCKernelModule + +主要用来作为Entity数据管理, 是本插件的核心模块，几乎所有的接口都是来自此模块, 主要用途为获取Entity对象, 获取/修改`Entity`的`Node`和`Table`数据, 同时可以注册公共的`ClassEvent`, `DataNodeEvent`, `DataTableEvent`(公共事件并不局限于某个Class/Entity) + +公共注册接口如下: + +```cpp +template +bool RegCommonClassEvent(BaseType* pBase, int (BaseType::*handler)(const AFGUID&, const std::string&, const ARK_ENTITY_EVENT, const AFIDataList&)) +{ + CLASS_EVENT_FUNCTOR functor = std::bind(handler, pBase, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4); + return RegCommonClassEvent(std::make_shared(functor)); +} + +template +bool RegCommonDataNodeEvent(BaseType* pBase, int (BaseType::*handler)(const AFGUID&, const std::string&, const AFIData&, const AFIData&)) +{ + DATA_NODE_EVENT_FUNCTOR functor = std::bind(handler, pBase, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4); + return RegCommonDataNodeEvent(std::make_shared(functor)); +} + +template +bool RegCommonDataTableEvent(BaseType* pBase, int (BaseType::*handler)(const AFGUID&, const DATA_TABLE_EVENT_DATA&, const AFIData&, const AFIData&)) +{ + DATA_TABLE_EVENT_FUNCTOR functor = std::bind(handler, pBase, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4); + return RegCommonDataTableEvent(std::make_shared(functor)); +} +``` + +数据获取接口如下: + +```cpp +virtual ARK_SHARE_PTR GetEntity(const AFGUID& ident) = 0; +virtual ARK_SHARE_PTR CreateEntity(const AFGUID& self, const int nSceneID, const int nGroupID, const std::string& strClassName, const std::string& strConfigIndex, const AFIDataList& arg) = 0; + + +virtual bool FindNode(const AFGUID& self, const std::string& name) = 0; + +virtual bool SetNodeBool(const AFGUID& self, const std::string& name, const bool value) = 0; +virtual bool SetNodeInt(const AFGUID& self, const std::string& name, const int32_t value) = 0; +virtual bool SetNodeInt64(const AFGUID& self, const std::string& name, const int64_t value) = 0; +virtual bool SetNodeFloat(const AFGUID& self, const std::string& name, const float value) = 0; +virtual bool SetNodeDouble(const AFGUID& self, const std::string& name, const double value) = 0; +virtual bool SetNodeString(const AFGUID& self, const std::string& name, const std::string& value) = 0; +virtual bool SetNodeObject(const AFGUID& self, const std::string& name, const AFGUID& value) = 0; + +virtual bool GetNodeBool(const AFGUID& self, const std::string& name) = 0; +virtual int32_t GetNodeInt(const AFGUID& self, const std::string& name) = 0; +virtual int64_t GetNodeInt64(const AFGUID& self, const std::string& name) = 0; +virtual float GetNodeFloat(const AFGUID& self, const std::string& name) = 0; +virtual double GetNodeDouble(const AFGUID& self, const std::string& name) = 0; +virtual const char* GetNodeString(const AFGUID& self, const std::string& name) = 0; +virtual const AFGUID GetNodeObject(const AFGUID& self, const std::string& name) = 0; +////////////////////////////////////////////////////////////////////////// +virtual AFDataTable* FindTable(const AFGUID& self, const std::string& name) = 0; +virtual bool ClearTable(const AFGUID& self, const std::string& name) = 0; + +virtual bool SetTableBool(const AFGUID& self, const std::string& name, const int row, const int col, const bool value) = 0; +virtual bool SetTableInt(const AFGUID& self, const std::string& name, const int row, const int col, const int32_t value) = 0; +virtual bool SetTableInt64(const AFGUID& self, const std::string& name, const int row, const int col, const int64_t value) = 0; +virtual bool SetTableFloat(const AFGUID& self, const std::string& name, const int row, const int col, const float value) = 0; +virtual bool SetTableDouble(const AFGUID& self, const std::string& name, const int row, const int col, const double value) = 0; +virtual bool SetTableString(const AFGUID& self, const std::string& name, const int row, const int col, const std::string& value) = 0; +virtual bool SetTableObject(const AFGUID& self, const std::string& name, const int row, const int col, const AFGUID& value) = 0; + +virtual bool GetTableBool(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual int32_t GetTableInt(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual int64_t GetTableInt64(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual float GetTableFloat(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual double GetTableDouble(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual const char* GetTableString(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +virtual const AFGUID GetTableObject(const AFGUID& self, const std::string& name, const int row, const int col) = 0; +``` + +举个数据获取的例子: + +```cpp +int AFCLevelModule::AddExp(const AFGUID& self, const int nExp) +{ + //通过DataNode名称获取ID为self的Entity数据 + int eJobType = m_pKernelModule->GetNodeInt(self, ARK::Player::Job()); + int nCurExp = m_pKernelModule->GetNodeInt(self, ARK::Player::EXP()); + int nLevel = m_pKernelModule->GetNodeInt(self, ARK::Player::Level()); + int nMaxExp = m_pPropertyConfigModule->CalculateBaseValue(eJobType, nLevel, ARK::Player::MAXEXP()); + + //Do something + + return 0; +} +``` \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/net-plugin.md b/docs/site/legacy-source/zh-cn/net-plugin.md new file mode 100644 index 000000000..5e4ff4c15 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/net-plugin.md @@ -0,0 +1 @@ +# 网络插件 \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/new-desgin.md b/docs/site/legacy-source/zh-cn/new-desgin.md new file mode 100644 index 000000000..6d2c2ec51 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/new-desgin.md @@ -0,0 +1,49 @@ +# 新的设计思路 + +## 数据管理 + +```text + |- MetaEntityClassSetting + |--- MetaClassSettingBase* ----| + | || |- MetaConfigClassSetting + | || + | || + | \||/ |- MetaEntityDataSetting + | \/ | +AFData -|--- MetaDataSettingBase* ----| + | | + | |- MetaConfigDataSetting + | + | |- bool + |--- Parent(AFData*) -----------|- enum + |- numberic(uint8/int8/uint16/int16/uint32/int32/uint64/int64/double/float) + |- string + |- struct(Map) + |- array(vector) + |- table(map) +``` + +## 数据说明 + +### MetaEntityClassSetting + +class_name +multi-MetaEntityDataSetting + +### MetaConfigClassSetting + +class_name +multi-MetaConfigDataSetting + +### MetaEntityDataSetting + +包含Type 和 Mask, 函数, 脚本等 + +### MetaConfigDataSetting + +只有类型和refer, 没有mask/其他函数等 + +## 参考 + +- Unreal4 +- KFrame \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/plan.md b/docs/site/legacy-source/zh-cn/plan.md new file mode 100644 index 000000000..13afe74fa --- /dev/null +++ b/docs/site/legacy-source/zh-cn/plan.md @@ -0,0 +1,74 @@ +# Plan + +## High priority + +- [x] excel格式修改为一张excel里放所有的schema,其他配置表分开来写,兼容现在的格式 +- [x] 调整代码风格统一 +- [x] spdlog升级 +- [x] 增加dirty data layer, 当一个客户端请求处理完成后统一下发变化数据，不能有变有发，会导致小包太碎，并且浪费协议的head(改为非实时数据下一帧统一发送，实时数据有变有发) +- [ ] 文档逐步补齐，概念介绍、设计理念、服务器架构、使用例子 +- [x] 所有的基础数据结构向C++容器看齐 +- [x] 服务中心注册(考虑etcd/consul来做), 已经使用consul来处理了 +- [x] 定时log和心跳改为timer方式，不要再是用update和HeartBeat了 +- [x] 修改配置打包工具(用Excel编辑，生成`xml`来给工程读取。为解决多人协作冲突, excel可以用名字后缀区分，类如Item.A.xlsx Item.B.xlsx) +- [x] 修改xml不再直接用rapidxml，用封装后的AFXml +- [x] 接口类重新设计纯粹化 +- [x] 增加生成器来生成重复代码(_插件类和模块类_) +- [x] 使用`std::chrono`改造`AFDateTime` +- [x] session id 使用GUID类型 +- [x] 增加murmur hash函数用来做consistent hash map +- [x] 增加xoshiro/xoroshiro随机算法 +- [x] 增加xxtea, crc16, crc32, crc64加密算法 +- [ ] 增加codec类，用来剥离框架对特定协议的依赖，方便外部替换协议类型 +- [ ] 增加插件动态热更新 +- [ ] 增加工具获取插件动态链接库版本号 +- [x] Linux下强杀进程处理(kill -9 xxx) +- [ ] 配置meta和entity meta的区分 +- [ ] 网络修改为asio系 +- [ ] web serever/client修改为asio/beast系 +- [ ] redis client修改为asio系 + +## Low priority + +- [x] Map, Layer,对应修改协议和Client的处理(**概念已经修改, 还未对接客户端**) +- [x] 关于背包类的table，整理或者交换，需要改成别的方式 +- [x] 优化数据同步的流量,减小属性同步的体积(去掉`NodeName`和`TableName`类似的string同步, 上线先同步index和name的映射，后续全部用index下发，入库用name) +- [x] 拓展DataTable的组成，例如道具包含了宝石(带经验，附魔等)、武器(带随机属性)等东西，DataTable现有的二维结构是特定的，不方便做扩展 +- [ ] 增加网络库和性能的基准测试用例，放到目录benchmark/unittest +- [ ] 增加kcp +- [ ] 脚本模块使用SWIG +- [x] 考虑使用ECS，全部对象Entity化，~~通过GUID来确定属于哪个分组的哪个位置，能快速定位和查找(通过守望先锋、ET、[ECS-unity](https://github.com/sschmid/Entitas-CSharp)，具体还要再调研)~~ +- [ ] 增加coroutine，参考libgo +- [ ] 引入tcmalloc +- [ ] 增加监控web页面(ant-design-for-vue) +- [ ] 增加Deployment web工具 +- [ ] ~~增加消息队列处理~~ +- [ ] 增加运维工具(tcm & deploy) +- [ ] 部分计算密集的地方使用多线程 +- [ ] 增加协议wrapper层，这样框架层包装后，可以甩出来给业务用，无需知道业务层用的协议类型 +- [ ] ~~升级至C++17~~ +- [ ] ~~`std::string_veiw`/`discard`/...~~ +- [ ] ~~插件加载顺序(通过配置中的字段, 或者通过配置的顺序)~~ +- [ ] ~~修改进程启动优先链接logserver，如果logserver连不上，则直接不能启动，这样就可以从一开始就能打log了~~ + +## Part finished + +- [x] spdlog增加按照文件夹/大小/小时滚动的sink(*已经修改了一部分，还需要进一步修改成tlog的格式，/data/binlog/1001/20180627/game1_hour.log*) +- [x] 增加consistent_hash_map + +## Finished + +- [x] 新架构修改 +- [x] 增加连接关系的配置，不再通过程序中手动设置关系(bus_relation, server_settting, IP和port不用再指定了, 通过获取IP和动态生成port), 网络地址修改为tcp://0.0.0.0:9001 wss://0.0.0.0:9001这样的URL +- [x] 修改bin文件夹debug和release在一起，debug和release分开配置(方便配置是一套) +- [x] guid改为内部指针类型(降低其他非guid类型的内存占用)***修改为int64_t了,不需要再考虑内存占用了*** +- [x] 增加网络插件,这样可以将网络模块和业务逻辑模块拆分开(现在NetClient和NetServer还是跟业务关联太紧密了) +- [x] net plugin增加endpoint +- [x] kernel和config插件还是得合并为一个，因为kernel非常依赖config插件 + +## Bugs + +- [x] ClearRow的时候后面的行号会变化，所以要考虑要么行号不变，只是置空，要么就得客户端来根据DeleteRow消息同步修改后续的row变化 +- [x] 现在的ConfigPlugin数据加载有问题 +- [x] AFMapEx的First Next返回值有问题 +- [ ] 单个进程开多个监听服务，busid会被覆盖和连接管理有问题 diff --git a/docs/site/legacy-source/zh-cn/quick-start.md b/docs/site/legacy-source/zh-cn/quick-start.md new file mode 100644 index 000000000..029c5f3dd --- /dev/null +++ b/docs/site/legacy-source/zh-cn/quick-start.md @@ -0,0 +1,108 @@ +# 快速开始 + +## 获取源码 + +git clone https://github.com/ArkNX/ARK.git + +or + +svn checkout https://github.com/ArkNX/ARK + +## 依赖库 +| 库名 | 版本 | 许可协议 | +| ----------------------------------------------------- | ------ | --------------------------------------------------------------------------------- | +| [brynet](https://github.com/IronsDu/brynet) | Master | [MIT](https://github.com/IronsDu/brynet/blob/master/LICENSE) | +| [spdlog](https://github.com/gabime/spdlog) | 0.17.0 | [MIT](https://github.com/gabime/spdlog/blob/v1.x/LICENSE) | +| [google protobuf](https://github.com/google/protobuf) | 3.5.x | [Google License](https://github.com/protocolbuffers/protobuf/blob/master/LICENSE) | +| [args](https://github.com/Taywee/args) | 6.2.0 | [MIT](https://github.com/Taywee/args/blob/master/LICENSE) | +| [rapidxml](http://rapidxml.sourceforge.net) | 1.13 | [LICENSE](http://rapidxml.sourceforge.net/license.txt) | + +## 支持的编译器 + +- GCC 4.9+ (**Recommend. Tested in Ubuntu 15.04**) +- MSVC VS2017 (**Recommend VS2019. Tested in Win7/10**) + +## 编译和运行 + +### Windows + +##### 前置准备 + +- Windows 7 以上 +- Visual Studio 2017 +- Git +- CMake 3.0+ + +##### 步骤 + +使用cmake + +1. 克隆源码 +2. 按步骤运行下面命令 + + ```batch + cd path/to/ARK + git submodule update --init + cd dep + md build + cd build + cmake -G "Visual Studio 16" -A x64 .. + ``` + +3. 编译 `ark.sln` +4. 运行 `path/to/ARK/bin/tools/gen-config.bat` 生成配置文件 +> [!WARNING] +> 需要安装Python3环境，需要的第三方库请查看`ARK/bin/tools/config_tool/README.md` + +5. 安装[Consul](https://consul.io), 启动命令为: + + ```bash + cd path/to/consul + consul.exe agent -server -ui -bootstrap-expect=1 -data-dir=./ -node=ark_consul_service -client=0.0.0.0 -bind=127.0.0.1 -log-file=./log/ -datacenter=ARK + ``` + +6. 运行脚本 `bin/rund.bat` + +> [!NOTE] +> 如果你使用其他Visual Studio版本, 请将`CMake命令行` 替换为正确的Visual Studio版本.
+ +### Linux + +##### 前置准备 + +- g++ 4.9+ (需要 C++ 11 和 std::regex) +- Git +- CMake 3.0+ +- libtool +- automake + +使用cmake + +1. 克隆源码 +2. 按步骤在终端运行下面命令 + + ```shell + cd path/to/ARK + git submodule update --init + mkdir -p build/debug && cd build/debug + cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=debug ../../ + make + ``` + +> [!NOTE] +> 如果你想编译`release`版本, 请使用`-DCMAKE_BUILD_TYPE=release`参数.
+为了加速编译, 你可以使用 `make -j [num]` 开启多核编译. 不过可能会消耗完你的系统内存. + +3. 运行 `path/to/ARK/bin/tools/gen-config.sh` 生成配置文件 + +> [!WARNING] +> 需要安装Python3环境，需要的第三方库请查看`ARK/bin/tools/config_tool/README.md` + +4. 安装[Consul](https://consul.io), 启动命令为: + + ```shell + cd path/to/consul + ./consul agent -server -ui -bootstrap-expect=1 -data-dir=./ -node=ark_consul_service -client=0.0.0.0 -bind=127.0.0.1 -log-file=./log/ -datacenter=ARK + ``` + +5. 运行脚本 `bin/rund.sh` \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/server-architecture.md b/docs/site/legacy-source/zh-cn/server-architecture.md new file mode 100644 index 000000000..83305af04 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/server-architecture.md @@ -0,0 +1 @@ +# 弹性服务器架构介绍 \ No newline at end of file diff --git a/docs/site/legacy-source/zh-cn/tools.md b/docs/site/legacy-source/zh-cn/tools.md new file mode 100644 index 000000000..518224808 --- /dev/null +++ b/docs/site/legacy-source/zh-cn/tools.md @@ -0,0 +1 @@ +# 工具介绍 \ No newline at end of file diff --git a/docs/site/package.json b/docs/site/package.json index 66e709a4c..ab52ba697 100644 --- a/docs/site/package.json +++ b/docs/site/package.json @@ -12,7 +12,7 @@ "build": "npm run prepare:content && astro build && node scripts/redirects.mjs", "preview": "astro preview", "typecheck": "npm run prepare:content && astro check", - "check": "node --test scripts/content.test.mjs && npm run typecheck && npm run build && node scripts/check-site.mjs", + "check": "node --test scripts/content.test.mjs scripts/legacy-source.test.mjs && npm run typecheck && npm run build && node scripts/check-site.mjs", "lint:docs": "nimbus-docs lint", "lint:docs:fix": "nimbus-docs lint --fix" }, diff --git a/docs/site/scripts/legacy-source.test.mjs b/docs/site/scripts/legacy-source.test.mjs new file mode 100644 index 000000000..f25e839bf --- /dev/null +++ b/docs/site/scripts/legacy-source.test.mjs @@ -0,0 +1,41 @@ +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { readFile, readdir } from "node:fs/promises"; +import { test } from "node:test"; +import { articles, sourceCommit } from "./migration-source.mjs"; + +const archive = new URL("../legacy-source/", import.meta.url); + +async function files(directory, prefix = "") { + const result = []; + for (const entry of await readdir(directory, { withFileTypes: true })) { + const name = prefix + entry.name; + if (entry.isDirectory()) result.push(...await files(new URL(entry.name + "/", directory), name + "/")); + else result.push(name); + } + return result; +} + +test("historical article archive preserves its snapshot, source mapping and exact bytes", async () => { + const readme = await readFile(new URL("README.md", archive), "utf8"); + assert.match(readme, new RegExp("Snapshot: `" + sourceCommit + "`")); + const attributes = await readFile(new URL(".gitattributes", archive), "utf8"); + assert.match(attributes, /^\*\.md -text$/m); + const checksums = new Map(); + for (const row of readme.matchAll(/^\| `([^`]+)` \| `([^`]+)` \| `([0-9a-f]{64})` \|$/gm)) { + assert.equal(checksums.has(row[1]), false, `duplicate provenance row: ${row[1]}`); + checksums.set(row[1], { target: row[2], digest: row[3] }); + } + const expected = Object.keys(articles).sort(); + assert.equal(expected.length, 40); + assert.deepEqual([...checksums.keys()].sort(), expected); + assert.deepEqual((await files(archive)).filter(file => file !== "README.md" && file !== ".gitattributes").sort(), expected); + for (const file of expected) { + assert.doesNotMatch(file, /(?:^\/|\.\.|\\)/, `source path is relative: ${file}`); + const record = checksums.get(file); + assert.equal(record.target, articles[file], `mapping for ${file}`); + const buffer = await readFile(new URL(file, archive)); + const digest = createHash("sha256").update(buffer).digest("hex"); + assert.equal(digest, record.digest, `original bytes changed: ${file}`); + } +}); diff --git a/docs/site/scripts/migration-source.mjs b/docs/site/scripts/migration-source.mjs index 5382c19aa..ee9b49956 100644 --- a/docs/site/scripts/migration-source.mjs +++ b/docs/site/scripts/migration-source.mjs @@ -1,4 +1,5 @@ -// Original Docsify content preserved by the Nimbus migration. +// Original Docsify bytes are archived in ../legacy-source/README.md. +// Modern guides may evolve; the archive records source paths and SHA256 checksums. export const sourceCommit = 'd2b1f31ee7ac77aa8c273a38ed7c60c0b534084d'; // Preserve Markdown entry points introduced before the site migration without