# Core

**命名空间**: `XCEngine::Core`

**类型**: `module`

**描述**: 提供基础类型别名、智能指针约定、引用计数基类、事件分发、层系统、文件写入以及若干基础子模块。

## 概览

`XCEngine::Core` 是引擎最底层的公共基础设施模块。它和业务功能相比更偏“支撑层”，为上层系统提供一组统一约定：

- 基础整数和字节类型
- 所有权和对象生命周期工具
- 事件分发机制
- Layer / LayerStack 这种运行时扩展组织方式
- 简单文件写入封装
- 更细分的 `Asset`、`Containers`、`IO`、`Math` 子模块

很多其他模块都会直接依赖它。例如：

- `Scene` 和 `Input` 直接使用 [Event](Event/Event.md)
- `ResourceManager` 使用 [SmartPtr](SmartPtr/SmartPtr.md) 里的 `MakeUnique`

所以这层文档最重要的不是列函数名，而是把“当前基础约定到底是什么”讲清楚。

## 设计要点

- `Core.h` 是 umbrella header，只聚合 `Types.h`、`RefCounted.h`、`SmartPtr.h`、`Event.h`，本身不引入新的运行时类型。
- `RefCounted` 和 `SmartPtr` 代表两套不同的 ownership 思路，当前实现并没有把它们自动打通。
- `Event` 是模板化的轻量事件广播器，强调易用性和复制回调安全，而不是高性能无分配事件总线。
- `Layer` / `LayerStack` 提供了一种类似应用框架栈的组织方式，但当前在代码库里的真实使用还很少。

## umbrella header

**头文件**: `XCEngine/Core/Core.h`

`Core.h` 当前只是一个 convenience include：

- `Types.h`
- `RefCounted.h`
- `SmartPtr.h`
- `Event.h`

它自己的命名空间体是空的，没有新增 class / struct / function。因此这里不再单独保留一页重复的“`Core` 类型页”，而是把它并入模块页说明。

## 子目录

- [Asset](Asset/Asset.md) - 资源句柄、异步加载与资源管理基础设施。
- [Containers](Containers/Containers.md) - 引擎自定义容器和字符串类型。
- [IO](IO/IO.md) - 路径与文件系统相关基础能力。
- [Math](Math/Math.md) - 向量、矩阵、四元数、颜色等数学基础设施。

## 顶层头文件

- [Event](Event/Event.md) - `Event.h`，模板化事件分发器。
- [FileWriter](FileWriter/FileWriter.md) - `FileWriter.h`，简单文件写入封装。
- [Layer](Layer/Layer.md) - `Layer.h`，Layer 基类。
- [LayerStack](LayerStack/LayerStack.md) - `LayerStack.h`，Layer 容器与调度顺序。
- [RefCounted](RefCounted/RefCounted.md) - `RefCounted.h`，侵入式原子引用计数基类。
- [SmartPtr](SmartPtr/SmartPtr.md) - `SmartPtr.h`，`shared_ptr` / `unique_ptr` 别名与工厂函数。
- [Types](Types/Types.md) - `Types.h`，基础整数别名。

## 推荐阅读顺序

1. 先读 [Core Foundations: Ownership, Events, And Layers](../../_guides/Core/Core-Foundations-Ownership-Events-And-Layers.md)。
2. 再读 [SmartPtr](SmartPtr/SmartPtr.md) 和 [RefCounted](RefCounted/RefCounted.md)，理解当前代码库里的 ownership 分层。
3. 然后读 [Event](Event/Event.md)，这是上层模块依赖最广的顶层类型之一。
4. 只有在需要应用框架栈语义时，再读 [Layer](Layer/Layer.md) 和 [LayerStack](LayerStack/LayerStack.md)。

## 相关指南

- [Core Foundations: Ownership, Events, And Layers](../../_guides/Core/Core-Foundations-Ownership-Events-And-Layers.md)

## 相关文档

- [上级目录](../XCEngine.md)
- [API 总索引](../../main.md)