diff --git a/wiki/concepts/Actor-Replication.md b/wiki/concepts/Actor-Replication.md new file mode 100644 index 00000000..317c75bd --- /dev/null +++ b/wiki/concepts/Actor-Replication.md @@ -0,0 +1,46 @@ +--- +title: "Actor Replication" +type: concept +tags: [] +sources: [unreal-multiplayer-architect] +last_updated: 2026-04-26 +--- + +## Definition +Actor 复制是 UE5 多人游戏网络同步的基础机制，允许 Actor 的属性和状态在服务器与所有客户端之间自动同步。通过 `UPROPERTY(Replicated)` 和 `GetLifetimeReplicatedProps()` 实现。 + +## Core Mechanisms +- `UPROPERTY(Replicated)` — 将属性标记为需要复制到所有客户端 +- `UPROPERTY(ReplicatedUsing=OnRep_X)` — 带通知函数的复制，客户端可在属性变化时执行逻辑 +- `DOREPLIFETIME_CONDITION` — 条件复制，如 `COND_OwnerOnly`、`COND_SimulatedOnly` +- `GetNetPriority()` — 控制 Actor 的复制优先级 +- `SetNetUpdateFrequency()` — 控制 Actor 的复制频率 + +## Key Implementation +```cpp +void AMyNetworkedActor::GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const +{ + Super::GetLifetimeReplicatedProps(OutLifetimeProps); + DOREPLIFETIME(AMyNetworkedActor, Health); + DOREPLIFETIME_CONDITION(AMyNetworkedActor, PrivateInventoryCount, COND_OwnerOnly); +} +``` + +## Best Practices +- 仅复制所有客户端都需要的状态 +- 使用 `COND_OwnerOnly` 减少私有状态的带宽消耗 +- 按 Actor 类型设置合适的 `NetUpdateFrequency`（大多数 20–30Hz） +- 使用 `ReplicatedUsing` 让客户端能响应属性变化 + +## Connection to Other Concepts +- [[Server-Authoritative Model]] — Actor Replication 是实现服务器权威的技术基础 +- [[Network Prediction]] — 客户端利用复制的状态进行预测和调和 +- [[Replication Graph]] — 空间分区优化复制性能 + +## Relationship to Agent +[[UnrealMultiplayerArchitect]] 强调 Actor 复制的正确实现是 UE5 多人游戏开发的第一步，必须从一开始就用 `DOREPLIFETIME_CONDITION` 进行带宽优化。 + +## Aliases +- UE5 Replication +- Property Replication +- State Synchronization diff --git a/wiki/concepts/AntiCheatArchitecture.md b/wiki/concepts/AntiCheatArchitecture.md new file mode 100644 index 00000000..c88f7f3d --- /dev/null +++ b/wiki/concepts/AntiCheatArchitecture.md @@ -0,0 +1,52 @@ +--- +title: "Anti-Cheat Architecture" +type: concept +tags: [networking, security, multiplayer] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- Server-Side Validation +- Anti-Cheat +- 服务器端验证 + +## Definition +反作弊架构是一套在服务器权威模型下**验证所有客户端输入**的设计原则和实现方案。由于客户端不可信，所有游戏关键操作必须在服务器端进行验证，拒绝非法请求并记录可疑行为。 + +## Core Principles +1. **永远不要信任客户端数据**：客户端发送的任何值都需要验证 +2. **服务器拥有最终裁判权**：位置、生命值、分数等由服务器计算 +3. **输入验证**：检查输入是否在物理上可行 +4. **速率限制**：检测并断开超出人类可能速度的 RPC 调用 + +## Unity (NGO) Implementation +```csharp +[ServerRpc] +private void SendInputServerRpc(Vector2 input, int tick) +{ + // 服务器端验证：物理上是否可能？ + float maxDistancePossible = _moveSpeed * Time.fixedDeltaTime * 2f; + if (Vector3.Distance(_serverPosition.Value, newPosition) > maxDistancePossible) + { + // 拒绝：瞬移检测或严重同步错误 + _serverPosition.Value = _serverPosition.Value; // 强制调和 + return; + } + _serverPosition.Value = newPosition; +} +``` + +## Key Techniques +- **移动验证**：速度上限检测、瞬移检测 +- **命中检测**：服务器端验证目标位置和碰撞 +- **审计日志**：记录所有游戏影响 RPC 的时间戳、玩家ID、动作类型 +- **速率限制**：每玩家每 RPC 类型的调用频率限制 + +## Related Concepts +- [[ServerAuthority]]: 反作弊的基础 +- [[UnityLobby]]: Lobby 数据不应包含游戏状态 +- [[BandwidthManagement]]: 带宽控制也是反作弊的一部分 + +## Related Entities +- [[UnityMultiplayerEngineer]]: 实现反作弊架构的专家 diff --git a/wiki/concepts/BandwidthManagement.md b/wiki/concepts/BandwidthManagement.md new file mode 100644 index 00000000..eec28620 --- /dev/null +++ b/wiki/concepts/BandwidthManagement.md @@ -0,0 +1,64 @@ +--- +title: "Bandwidth Management" +type: concept +tags: [networking, performance, multiplayer] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- Network Bandwidth Optimization +- 带宽管理 + +## Definition +带宽管理是在多人游戏中**控制网络流量**的技术和策略，目标是在有限的带宽下提供流畅的游戏体验。典型目标：每玩家稳态带宽 < 10KB/s。 + +## Core Techniques + +### 1. Dirty Check（脏值检查） +`NetworkVariable` 仅在值真正变化时触发同步，避免重复设置： +```csharp +// BAD: 每帧设置相同值 → 无意义网络流量 +void Update() { + Position.Value = transform.position; // 即使位置没变也同步！ +} + +// GOOD: 值真正变化才同步 +void FixedUpdate() { + if (Vector3.Distance(transform.position, lastPosition) > 0.01f) + { + Position.Value = transform.position; + lastPosition = transform.position; + } +} +``` + +### 2. Throttling（限流） +非关键状态更新频率限制： +- 生命值条：最高 1Hz +- 分数：最高 1Hz +- 位置同步：使用 NetworkTransform 而非每帧 NetworkVariable + +### 3. Delta Compression（差分压缩） +对复杂结构使用 `INetworkSerializable` 只同步增量： +```csharp +public struct ComplexState : INetworkSerializable +{ + public Vector3 position; + public Quaternion rotation; + // 只同步变化的部分 +} +``` + +### 4. Object Pooling（对象池） +NGO NetworkObject 的 spawn/despawn 成本高，对频繁创建的对象使用对象池复用。 + +## Performance Target +- 每玩家稳态带宽：< 10KB/s +- 峰值带宽（事件触发时）：< 50KB/s +- 同步延迟容忍：200ms 延迟下无明显卡顿 + +## Related Concepts +- [[NetworkVariable]]: 带宽管理的核心对象 +- [[ClientPrediction]]: 预测减少对服务器状态的依赖 +- [[UnityMultiplayerEngineer]]: 负责带宽优化的专家 diff --git a/wiki/concepts/ClientPrediction.md b/wiki/concepts/ClientPrediction.md new file mode 100644 index 00000000..6d19c473 --- /dev/null +++ b/wiki/concepts/ClientPrediction.md @@ -0,0 +1,40 @@ +--- +title: "Client Prediction" +type: concept +tags: [networking, multiplayer, latency] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- Client-Side Prediction +- 客户端预测 + +## Definition +客户端预测是一种在服务器权威模型下的优化技术，允许客户端**立即执行输入预测移动**，无需等待服务器确认，从而提供流畅的用户体验。当服务器状态与客户端预测不一致时，触发**调和（Reconciliation）**机制进行校正。 + +## How It Works (Unity NGO Pattern) +1. 客户端读取本地输入，立即更新本地渲染位置 +2. 客户端通过 `ServerRpc` 发送输入到服务器 +3. 服务器模拟输入，更新权威状态，广播给所有客户端 +4. 客户端在 `LateUpdate` 中比较预测位置与服务器位置 +5. 当偏差超过阈值时，强制将客户端位置回正到服务器位置 + +## Key Parameters +- `ReconciliationThreshold`: 触发回正的偏差阈值（建议 0.5 单位） +- 输入队列：客户端缓存最近 N 帧的输入，用于服务器重模拟 + +## Related Concepts +- [[ServerAuthority]]: 客户端预测的先决条件 +- [[LagCompensation]]: 与延迟补偿协同工作 +- [[NetworkVariable]]: 用于同步服务器权威状态 + +## Unity Implementation Pattern +```csharp +// Reconciliation logic in LateUpdate +if (Vector3.Distance(transform.position, _serverPosition.Value) > _reconciliationThreshold) +{ + _clientPredictedPosition = _serverPosition.Value; + transform.position = _clientPredictedPosition; +} +``` diff --git a/wiki/concepts/Core-Gameplay-Loop.md b/wiki/concepts/Core-Gameplay-Loop.md new file mode 100644 index 00000000..b06e6c72 --- /dev/null +++ b/wiki/concepts/Core-Gameplay-Loop.md @@ -0,0 +1,52 @@ +--- +title: "Core Gameplay Loop" +type: concept +tags: [game-design, player-experience, engagement] +sources: [game-designer] +last_updated: 2026-04-26 +--- + +## Definition + +Core Gameplay Loop（核心游戏循环）是一套驱动玩家持续参与的三层循环结构——从瞬间决策（0-30秒）到会话目标（5-30分钟）再到长期进阶（数小时至数周）。它决定了游戏能否在多个时间尺度上维持玩家兴趣。 + +## Three-Layer Structure + +### 1. Moment-to-Moment Loop（瞬间体验，0–30秒） +玩家在极短时间内的重复决策与反馈。 +- **Action**：玩家执行具体操作（跳跃/射击/收集） +- **Feedback**：即时视觉/音效/触觉反馈 +- **Reward**：资源/进度/内在满足感 + +> 核心问题：这个操作本身好玩吗？在没有升级、没有故事的情况下，它能独立成立吗？ + +### 2. Session Loop（会话循环，5–30分钟） +玩家单次游戏会话中的目标与张力。 +- **Goal**：完成目标以解锁奖励 +- **Tension**：风险或资源压力（如时间限制、随机事件） +- **Resolution**：胜负状态与后果 + +### 3. Long-Term Loop（长期循环，小时–周） +驱动玩家持续回流的元进度与留存机制。 +- **Progression**：解锁树 / 元进度系统 +- **Retention Hook**：每日奖励 / 赛季内容 / 社交循环 + +## Design Principles + +1. **每一层都必须独立成立**——长期循环坍塌时，瞬间体验仍能支撑短期参与 +2. **各层相互增强**——瞬间体验的积累推动会话目标，会话目标的完成推动长期进度 +3. **最小可行复杂度**——仅添加产生新颖决策的循环，移除不产生意义的复杂性 +4. **"有趣假设"优先**——在纸面原型阶段验证核心循环的可玩性，而非在完整系统构建后 + +## Relationship to Game Design Document + +Core Gameplay Loop 是 GDD 的核心章节，与以下交付物对应： +- **Mechanic Specification**：定义瞬间循环中的每个具体操作 +- **Economy Balance Spreadsheet**：定义会话循环中的资源流 +- **Player Archetypes**（鲸鱼/海豚/小鱼）：定义长期循环中的不同玩家路径 + +## Related Concepts + +- [[Economy Balance]]：经济系统为会话循环和长期循环提供资源基础 +- [[Player Onboarding]]：引导流程必须快速呈现瞬间循环的可玩性 +- [[Systemic Design]]：次级系统应与核心循环交互以产生涌现性策略 diff --git a/wiki/concepts/Economy-Balance.md b/wiki/concepts/Economy-Balance.md new file mode 100644 index 00000000..44499775 --- /dev/null +++ b/wiki/concepts/Economy-Balance.md @@ -0,0 +1,75 @@ +--- +title: "Economy Balance" +type: concept +tags: [game-design, economy, monetization, balance] +sources: [game-designer] +last_updated: 2026-04-26 +--- + +## Definition + +Economy Balance（经济平衡）是游戏内资源流通系统的设计与调优过程——通过控制来源（source）、汇点（sink）和均衡曲线，确保游戏经济在不同玩家路径上都保持健康（无无限循环、无死胡同、无通胀/通缩）。 + +## Core Framework + +### Supply & Demand Model + +游戏经济本质上是资源的供给-需求系统： +- **Source**（资源来源）：玩家获取货币/道具的途径（任务奖励/掉落/购买） +- **Sink**（资源汇点）：资源被消耗的途径（升级/强化/交易税/销毁） +- **Equilibrium**：供需平衡曲线，决定经济稳定性 + +> 失衡信号：Source > Sink → 通货膨胀（资源贬值）；Source < Sink → 通货紧缩（玩家挫败感） + +### Player Archetypes + +不同付费意愿的玩家需要不同的经济设计： +- **Whales（鲸鱼）**：高付费，需要 Prestige Sink（声望消耗机制）防止经济饱和 +- **Dolphins（海豚）**：中等付费，需要 Value Sink（性价比消耗机制） +- **Minnows（小鱼）**：免费玩家，需要 Earnable Aspirational Goals（可获取的激励目标） + +## Inflation Detection + +定义关键指标并设置阈值： +- **Metric**：每活跃玩家每日货币增量（Currency per Active Player per Day） +- **Threshold**：当指标超过预设值时触发平衡调整流程 +- **Adjustment**：调整 Source（降低产出）或 Sink（增加消耗）以恢复平衡 + +## Advanced Methods + +### Monte Carlo Simulation + +在代码实现前对进度曲线进行蒙特卡洛模拟： +- 模拟 1000+ 随机玩家路径 +- 识别极端情况（极速通关 vs 长期卡关） +- 提前发现经济漏洞 + +### Paper Simulation + +在电子表格中进行玩家经济路径模拟： +- 穷举主要玩家路径 +- 验证无无限资源获取循环 +- 测试边界条件（最小/最大资源持有量） + +## Design Standards + +| Variable | Base Value | Min | Max | Tuning Notes | +|----------|-----------|-----|-----|--------------| +| Player HP | 100 | 50 | 200 | Scales with level | +| Enemy Damage | 15 | 5 | 40 | [PLACEHOLDER] - test at level 5 | +| Resource Drop % | 0.25 | 0.1 | 0.6 | Adjust per difficulty | +| Ability Cooldown | 8s | 3s | 15s | Feel test required | + +> 所有数值从假设开始，用 `[PLACEHOLDER]` 标记，直至通过测试验证 + +## Relationship to Core Gameplay Loop + +Economy Balance 支撑会话循环和长期循环： +- **会话循环**：资源稀缺性制造张力（Source - Sink = 可用资源） +- **长期循环**：货币通胀/通缩直接影响玩家成就感曲线 + +## Related Concepts + +- [[Core Gameplay Loop]]：经济系统为循环提供资源流通基础 +- [[Behavioral Economics in Games]]：经济设计中的行为心理学应用（损失厌恶、变率奖励） +- [[Player Archetypes]]：不同付费玩家的经济需求差异 diff --git a/wiki/concepts/GAS-Gameplay-Ability-System.md b/wiki/concepts/GAS-Gameplay-Ability-System.md new file mode 100644 index 00000000..0032c33b --- /dev/null +++ b/wiki/concepts/GAS-Gameplay-Ability-System.md @@ -0,0 +1,65 @@ +--- +title: "GAS (Gameplay Ability System)" +type: concept +tags: [unreal-engine, networking, multiplayer, ue5, abilities] +sources: ["unreal-multiplayer-architect", "unreal-systems-engineer"] +last_updated: 2026-04-26 + +## Additional Sources +Gameplay Ability System（GAS）是 UE5 的可扩展技能与属性框架，通过 UGameplayAbility、UAttributeSet、UAbilitySystemComponent 实现网络就绪的技能系统。[[UnrealSystemsEngineer]] 补充：所有 Tick 逻辑必须 C++；FGameplayTag 优于字符串标识符；通过 UPROPERTY(ReplicatedUsing=OnRep_Health) + GAMEPLAYATTRIBUTE_REPNOTIFY 宏实现属性复制。 + +## Core Components +- **UAbilitySystemComponent**：GAS 核心组件，管理技能和属性，必须正确配置网络复制 +- **UGameplayAbility**：可激活的技能类，支持网络预测和复制 +- **FGameplayEffectContext**：技能效果上下文，携带命中结果、来源和自定义数据 +- **FPredictionKey**：预测键，标记可预测的能力和属性变更，支持服务器确认或回滚 +- **UAttributeSet**：属性集，包含可复制的游戏属性（生命值、能量等） + +## Network Integration (Dual Init Path) +GAS 在多人游戏中必须实现双路径初始化： + +```cpp +// 服务器路径 — PossessedBy 在 Actor 被 Controller 拥有时调用 +void AMyCharacter::PossessedBy(AController* NewController) +{ + Super::PossessedBy(NewController); + AbilitySystemComponent->InitAbilityActorInfo(GetPlayerState(), this); +} + +// 客户端路径 — OnRep_PlayerState 在 PlayerState 复制到达时调用 +void AMyCharacter::OnRep_PlayerState() +{ + Super::OnRep_PlayerState(); + AbilitySystemComponent->InitAbilityActorInfo(GetPlayerState(), this); +} +``` + +## Network Prediction in GAS +- `FPredictionKey`：标记所有预测变更，服务器确认后生效 +- 客户端预测技能激活和属性变更 +- 服务器验证并广播 `GameplayEffect` 到所有客户端 +- 验证失败时服务器回滚客户端预测 + +## Best Practices +- **双路径初始化**：必须在 `PossessedBy` 和 `OnRep_PlayerState` 两个入口点初始化 GAS +- **AttributeSet 复制**：使用 `UPROPERTY(Replicated)` 让属性在服务器和客户端同步 +- **预测管理**：高频技能必须正确设置 `NetDeltaFrequency` 避免带宽爆炸 +- **预测键作用域**：`FPredictionKey` 必须在能力激活时生成并传递给所有子操作 + +## Connection to Other Concepts +- [[Actor Replication]] — GAS 依赖 Actor 复制机制同步属性和状态 +- [[Network Prediction]] — GAS 内置网络预测支持（FPredictionKey） +- [[Server-Authoritative Model]] — 服务器权威验证技能激活请求 + +## Relationship to Agent +[[UnrealMultiplayerArchitect]] 强调：GAS 网络集成必须从双路径初始化开始，测试必须在 150ms 模拟延迟下验证技能激活，"Profile GAS replication overhead" 是网络优化的关键步骤。 + +[[UnrealSystemsEngineer]] 补充：系统架构师负责 UGameplayAbility/UAttributeSet C++ 实现和 BlueprintCallable 暴露；Tick 依赖逻辑必须 C++（即使是技能冷却检查）；AttributeSet 使用 FGameplayAttributeData + GAMEPLAYATTRIBUTE_REPNOTIFY 宏保证复制安全。 + +## Aliases +- Gameplay Ability System +- UE5 GAS +- AbilitySystemComponent +- FPredictionKey +- GameplayEffect +- AttributeSet diff --git a/wiki/concepts/LOD.md b/wiki/concepts/LOD.md new file mode 100644 index 00000000..27e99375 --- /dev/null +++ b/wiki/concepts/LOD.md @@ -0,0 +1,37 @@ +--- +title: "LOD" +type: concept +tags: ["game-engine", "performance-optimization", "3d-graphics"] +sources: ["unreal-technical-artist", "unreal-world-builder"] +last_updated: 2026-04-26 +--- + +## Definition +Level of Detail（LOD），根据渲染对象与摄像机距离动态切换网格体精度（或着色复杂度）的机制。是 3D 游戏引擎性能优化的基础技术。 + +## LOD Strategy +- **Nanite 资产**：自动 LOD，无需手动配置 +- **非 Nanite 资产**（骨骼网格体、样条线、程序化网格体）：必须手动配置 LOD 链，并验证距离过渡 + +## Manual LOD Chain Requirements +- 每个资产必须定义 LOD0–LOD3 最低要求 +- 过渡距离必须在目标硬件上验证 +- 开放世界道具（无 Nanite）超过 500 三角形须有文档化例外 + +## Cull Distance +LOD 之外还需要 Cull Distance Volumes 配置远距离剔除： +- 按资产类别设置，非全局统一 +- 所有开放世界关卡必须配置 + +## HLOD（Hierarchical LOD） +- World Partition 开放世界的必备配置 +- 将多个小对象合并为大型远距离代理 +- 必须为所有室外区域生成 HLOD + +## Relationship to Nanite +Nanite 本质上是自动 LOD 系统，适用于静态几何体。LOD 链是手动 LOD 系统，用于 Nanite 无法处理的资产类型。 + +## Related +- [[Nanite]] — 自动 LOD 系统 +- [[PerformanceBudget]] — LOD 是帧预算控制的核心工具 +- [[WorldPartition]] — HLOD 的配合框架 diff --git a/wiki/concepts/LagCompensation.md b/wiki/concepts/LagCompensation.md new file mode 100644 index 00000000..8c8c09d2 --- /dev/null +++ b/wiki/concepts/LagCompensation.md @@ -0,0 +1,36 @@ +--- +title: "Lag Compensation" +type: concept +tags: [networking, multiplayer, latency] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- Server-Side Lag Compensation +- 延迟补偿 + +## Definition +延迟补偿是一种在服务器权威模型下**考虑网络延迟影响**的技术。当服务器处理客户端的射击/命中请求时，需要将客户端的请求时间「回溯」到网络延迟对应的时间点，以提供公平的命中判定。 + +## Problem It Solves +在没有延迟补偿的情况下： +- 客户端 A 看到命中了客户端 B +- 但由于网络延迟，B 已经移动到了新位置 +- 结果：A 的命中被服务器拒绝，但 A 看到的是命中效果 → 体验不一致 + +## Standard Approach +1. 客户端发送带有**时间戳**的输入/射击请求 +2. 服务器根据网络延迟计算**回溯时间** +3. 服务器将目标玩家「回放」到回溯时间点的位置 +4. 在该位置进行命中判定 +5. 结果同步给所有客户端 + +## Related Concepts +- [[ServerAuthority]]: 延迟补偿依赖服务器权威 +- [[ClientPrediction]]: 两者结合提供流畅且公平的游戏体验 +- [[AntiCheatArchitecture]]: 延迟补偿同时是反作弊的重要手段 + +## Related Entities +- [[UnityMultiplayerEngineer]]: 实现延迟补偿的专家 +- [[UnrealMultiplayerArchitect]]: 虚幻引擎中的对应实现 diff --git a/wiki/concepts/LargeWorldCoordinates.md b/wiki/concepts/LargeWorldCoordinates.md new file mode 100644 index 00000000..da33dbd3 --- /dev/null +++ b/wiki/concepts/LargeWorldCoordinates.md @@ -0,0 +1,40 @@ +--- +title: "Large World Coordinates" +type: concept +tags: ["unreal-engine", "coordinate-system", "precision", "ue5", "open-world"] +sources: ["unreal-world-builder"] +last_updated: 2026-04-26 +--- + +## Definition +Large World Coordinates（LWC），UE5 双精度坐标系统，通过在引擎层面使用 double（64 位浮点）替代 float（32 位浮点）存储世界位置坐标，解决超大世界（>2km）远距离处的浮点精度误差问题。 + +## The Precision Problem +- 单精度浮点（float）在距离原点约 20km 处开始出现可见精度误差 +- 误差表现：抖动（Jitter）、接缝（Seam）、几何体重影（Ghosting） +- 开放世界项目（4km² ~ 64km²）极易触碰到此阈值 + +## When LWC is Required +- **任何轴超过 2km 的世界必须启用 LWC** +- 测试方法：在距离原点 100km 处生成玩家，验证无视觉或物理瑕疵 + +## LWC Compatibility Requirements +### Shader/Material +- 替换所有直接 world position 采样为 `LWCToFloat()` 函数 +- 否则可能导致远处的材质出现视觉错误 + +### Gameplay Code +- 世界位置使用 `FVector3d`（双精度）而非 `FVector`（单精度） +- 特别是在处理坐标计算、Actor 放置、寻路等逻辑时 + +### Asset Pipeline +- 检查第三方 DDC（Derived Data Cache）资产是否正确配置 LWC +- 某些旧资产导入流程可能未处理双精度坐标 + +## Relationship to World Partition +LWC 与 World Partition 协同：World Partition 管理大世界的分区流送，LWC 解决大世界的坐标精度问题，两者共同支撑 UE5 开放世界技术栈。 + +## Related +- [[UnrealWorldBuilder]] — LWC 配置与审计专家 +- [[WorldPartition]] — LWC 的配套分区管理框架 +- [[Nanite]] — Nanite 虚拟几何体在大世界中的使用不受 LWC 影响（Nanite 内部使用相对坐标） diff --git a/wiki/concepts/MaterialFunction.md b/wiki/concepts/MaterialFunction.md new file mode 100644 index 00000000..1a1bccbb --- /dev/null +++ b/wiki/concepts/MaterialFunction.md @@ -0,0 +1,28 @@ +--- +title: "MaterialFunction" +type: concept +tags: ["unreal-engine", "materials", "shader"] +sources: ["unreal-technical-artist"] +last_updated: 2026-04-26 +--- + +## Definition +UE5 Material Editor 中可封装、可复用的节点逻辑单元。封装一组节点图作为黑盒函数，供多个 Master Material 引用。 + +## Purpose +消除跨 Master Material 的重复节点簇，确保同一逻辑只需维护一处。 + +## Usage in This Wiki +- [[unreal-technical-artist]] 强制规定：所有可复用逻辑必须封装为 Material Function，禁止在多个 Master Material 间重复节点簇 +- 示例：MF_TriplanarMapping（三平面映射）封装 WorldPosition 投影逻辑，可在任意岩石、悬崖、地形混合材质中使用 + +## Key Principles +- 单一职责：一个 Function 只做一件事（三平面映射 / 噪声叠加 / 顶点偏移等） +- 输入输出清晰：所有可调参数通过 Input 节点暴露 +- 禁止副作用：Function 内部不应修改外部状态 +- 避免 Static Switch 嵌套：每个 Static Switch 使引用该 Function 的材质排列数翻倍 + +## Related +- [[MaterialEditor]] — Material Function 的创作环境 +- [[QualitySwitch]] — 同一材质内的质量分层机制 +- [[NiagaraVFX]] — VFX 系统，类似 Function 的模块化复用理念 diff --git a/wiki/concepts/Nanite.md b/wiki/concepts/Nanite.md new file mode 100644 index 00000000..96890775 --- /dev/null +++ b/wiki/concepts/Nanite.md @@ -0,0 +1,37 @@ +--- +title: "Nanite" +type: concept +tags: ["unreal-engine", "geometry", "performance-optimization"] +sources: ["unreal-technical-artist", "unreal-systems-engineer", "unreal-world-builder"] +last_updated: 2026-04-26 +--- + +## Definition +UE5 虚拟几何体系统（Virtualized Geometry System），支持自动 LOD 和海量实例化渲染。Nanite 将几何体视为由微小三角形组成的流式资源，根据屏幕空间距离动态选择精度。 + +## Key Properties +- **自动 LOD**：无需手动配置 LOD 链，系统自动处理 +- **海量实例**：支持数千个网格体同时渲染，由 PCG 驱动时尤为重要 +- **确定性精度**：相同场景始终产生相同的三角形流 +- **Nanite 禁用例外**：骨骼网格体、样条线网格体、程序化网格体无法使用 Nanite，必须手动配置 LOD 链 + +## In the PCG Pipeline +所有 PCG 放置的静态网格体必须在 Nanite 适用时启用。PCG 的高密度特性（数千实例）与 Nanite 的海量渲染能力天然契合。 + +## LOD vs Nanite +| 特性 | 手动 LOD | Nanite | +|------|---------|--------| +| 精度切换 | 固定距离阈值 | 屏幕空间连续 | +| 配置成本 | 高（需逐资产手动配置） | 低（启用即可） | +| 适用资产 | 所有类型 | 静态网格体 | +| 骨骼/程序化 | 支持 | 不支持 | + +## Performance Implication +- 无 Nanite 资产的开放世界道具：禁止超过 500 三角形且无文档化例外 +- Cull Distance：Nanite 资产的远距离剔除仍通过 Cull Distance Volumes 配置 +- **[[UnrealSystemsEngineer]] 补充**：单场景硬上限 **1600 万实例**，开放世界项目需提前规划实例预算；Nanite 隐式在像素着色器推导切线空间（减少几何数据体积），因此 Nanite 网格不得存储显式切线；Nanite 不兼容骨骼网格（用标准 LOD）、复杂 clip 操作的遮罩材质（需性能基准测试）、样条网格和程序化网格组件；使用 `r.Nanite.Visualize` 模式提前发现兼容性问题 + +## Related +- [[LOD]] — 非 Nanite 资产的 LOD 链配置 +- [[PCG]] — Nanite 的主要应用场景 +- [[PerformanceBudget]] — Nanite 是开放世界性能预算的关键工具 diff --git a/wiki/concepts/Network-Prediction.md b/wiki/concepts/Network-Prediction.md new file mode 100644 index 00000000..a7f513a8 --- /dev/null +++ b/wiki/concepts/Network-Prediction.md @@ -0,0 +1,45 @@ +--- +title: "Network Prediction" +type: concept +tags: [] +sources: [unreal-multiplayer-architect] +last_updated: 2026-04-26 +--- + +## Definition +网络预测是 UE5 多人游戏中减少客户端感知延迟的核心技术。客户端在发送输入到服务器的同时，本地执行游戏逻辑（预测结果），当服务器确认结果返回时，客户端对比并调和（Reconcile）任何差异。 + +## Why It Matters +即使服务器在 100ms 后才返回结果，客户端通过预测可以让玩家感受到即时响应： + +``` +客户端发送输入 → 本地预测执行 → 显示预测结果（立即）→ 服务器执行 → 客户端调和（100ms后） +``` + +## Prediction in UE5 +- **Movement Prediction**：角色移动在客户端本地预测 +- **Ability Prediction (GAS)**：`FPredictionKey` 标记所有预测变更，服务器确认或回滚 +- **Reconciliation**：服务器权威结果与客户端预测结果对比时，自动校正客户端状态 + +## Key Methods +- `NetMulticast Unreliable` — 服务器向所有客户端广播，用于触发预测性的视觉效果 +- `FPredictionKey` — GAS 中的预测键，标记可预测的能力和属性变更 +- `p.NetShowCorrections 1` — 调试命令，可视化调和事件 + +## Prediction Pitfalls +- 过度预测会导致大量回滚（Rollback），影响游戏体验 +- 仅预测确定性输入（移动、射击）——不预测随机事件 +- 在高延迟（>200ms）环境下需要特别调优预测容差 + +## Connection to Other Concepts +- [[Server-Authoritative Model]] — 预测依赖服务器最终权威结果 +- [[Actor Replication]] — 复制的状态是预测和调和的数据基础 +- [[RPC (Remote Procedure Call)]] — 客户端通过 Server RPC 发送输入触发预测 + +## Relationship to Agent +[[UnrealMultiplayerArchitect]] 强调："Desync events (reconciliations) < 1 per player per 30 seconds at 200ms ping" 是成功指标，网络预测的质量直接影响该指标。 + +## Aliases +- Client-Side Prediction +- Rollback Prediction +- Reconciliation diff --git a/wiki/concepts/NetworkVariable.md b/wiki/concepts/NetworkVariable.md new file mode 100644 index 00000000..512caa88 --- /dev/null +++ b/wiki/concepts/NetworkVariable.md @@ -0,0 +1,44 @@ +--- +title: "NetworkVariable" +type: concept +tags: [networking, unity, ngo] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- NetworkVariable +- NV (abbreviation) + +## Definition +`NetworkVariable` 是 Unity Netcode for GameObjects（NGO）中的核心类型，用于**持久化复制状态**——当值发生变化时，自动通过网络同步到所有客户端。仅在值真正变化时触发同步（dirty check）。 + +## Usage Rules +| 场景 | 应使用 | +|------|--------| +| 持久化、需要同步的状态 | `NetworkVariable` | +| 一次性事件、触发通知 | `ClientRpc` / `ServerRpc` | + +**核心原则：持久化用 NetworkVariable，一次性事件用 RPC，不可混用。** + +## Bandwidth Considerations +- **避免在 Update() 中重复设置相同值**——触发无意义的网络同步 +- 对高频数值使用差分压缩（`INetworkSerializable`） +- 非关键状态（血条、分数）限流至最高 10Hz + +## Example +```csharp +// 健康值：持久化 → NetworkVariable +public NetworkVariable PlayerHealth = new(100, + NetworkVariableReadPermission.Everyone, + NetworkVariableWritePermission.Server); + +// 命中特效：一次性事件 → ClientRpc +[ClientRpc] +public void OnHitClientRpc(Vector3 hitPoint) { ... } +``` + +## Related Concepts +- [[ServerAuthority]]: NetworkVariable 体现服务器权威 +- [[BandwidthManagement]]: 优化 NetworkVariable 使用 +- [[ClientPrediction]]: 结合 NetworkVariable 实现客户端预测 diff --git a/wiki/concepts/NiagaraVFX.md b/wiki/concepts/NiagaraVFX.md new file mode 100644 index 00000000..e5438512 --- /dev/null +++ b/wiki/concepts/NiagaraVFX.md @@ -0,0 +1,42 @@ +--- +title: "NiagaraVFX" +type: concept +tags: ["unreal-engine", "vfx", "particle-systems"] +sources: ["unreal-technical-artist"] +last_updated: 2026-04-26 +--- + +## Definition +UE5 新一代粒子和 VFX（视觉效果）系统，替代旧版 Cascade。核心设计理念：GPU/CPU 模拟分离、模块化可复用、Scalability 分级预设。 + +## Key Design Decisions +- **GPU vs CPU 选择**：粒子数 < 1000 用 CPU 模拟；粒子数 > 1000 用 GPU 模拟 +- **Max Particle Count 强制**：所有系统必须设置硬上限，禁止无限粒子 +- **Scalability 三档预设**：High（PC/主机高端）、Medium（主机基准/中端 PC）、Low（移动/性能模式），必须全部测试后交付 + +## Scalability Preset Example +| 档位 | 最大活跃系统数 | 每系统最大粒子数 | 剔除距离 | +|------|--------------|----------------|---------| +| High | 10 | 50 | — | +| Medium | 6 | 25 | 30m | +| Low | 3 | 10 | 15m | + +## Key Modules +- Initialize Particle：生命周期、缩放、颜色参数化 +- Initial Velocity：锥形扩散、重力方向 +- Drag：水平摩擦力控制扩散范围 +- Scale Color/Opacity：线性淡出曲线 + +## Rendering +- Sprite Renderer + T_Particle 纹理集（4×4 帧动画） +- Blend Mode: Translucent，峰值时最多 3 层 overdraw + +## Advanced Capabilities +- GPU Simulation Stages：流体类粒子动力学（邻居查询、压力、速度场） +- Data Interface：查询物理场景数据、网格表面、音频频谱 +- Parameter Collections：接收游戏状态参数，实现 VFX 实时响应玩法 + +## Related +- [[VFX]] — 游戏 VFX 通用概念 +- [[PerformanceBudget]] — Niagara 帧预算管理 +- [[QualitySwitch]] — 材质质量分层，与 Niagara Scalability 理念一致 diff --git a/wiki/concepts/PCG.md b/wiki/concepts/PCG.md new file mode 100644 index 00000000..1a15bbe0 --- /dev/null +++ b/wiki/concepts/PCG.md @@ -0,0 +1,38 @@ +--- +title: "PCG" +type: concept +tags: ["unreal-engine", "procedural-generation", "open-world"] +sources: ["unreal-technical-artist", "unreal-world-builder"] +last_updated: 2026-04-26 +--- + +## Definition +Procedural Content Generation（程序化内容生成），UE5 框架，通过图节点控制开放世界资产分布、地形采样、密度过滤和实例化放置。输出确定性：相同输入图和参数始终产生相同结果。 + +## Core Pipeline +1. **Input**：Landscape Surface Sampler → 密度和坡度过滤 +2. **Transform Points**：Jitter 位置（±1.5m XY）、随机旋转（仅 Yaw）、缩放变化（0.8–1.3） +3. **Density Filter**：Poisson Disk 最小间距（防止重叠）、Biome 密度纹理采样 +4. **Exclusion Zones**：道路缓冲（5m）、玩家路径缓冲（3m）、手动放置 Actor 排除半径（10m） +5. **Static Mesh Spawner**：权重分配（橡树 40%、松树 35%、桦树 20%、枯树 5%），全启用 Nanite + +## Parameter Interface（必须文档化） +- GlobalDensityMultiplier（0.0–2.0） +- MinSeparationDistance（1.0–5.0m） +- EnableRoadExclusion（bool） + +## Performance Constraints +- 最差情况下生成时间 < 3 秒 +- 流式加载不得造成帧卡顿（World Partition 配合） +- PCG 密度控制：PCG → Nanite，密度可扩展至数千实例 + +## Advanced Patterns +- Gameplay Tags 查询驱动环境分布规则 +- 递归 PCG：图 A 的输出作为图 B 的输入 +- Runtime PCG：几何体破坏后重新运行图 +- PCG 调试工具：编辑器视口内可视化点密度、属性值、排除区边界 + +## Related +- [[Nanite]] — PCG 放置资产的首选渲染模式 +- [[WorldPartition]] — 与 PCG 流式加载协同 +- [[Procedural-Level-Design]] — 更广义的程序化关卡设计概念 diff --git a/wiki/concepts/QualitySwitch.md b/wiki/concepts/QualitySwitch.md new file mode 100644 index 00000000..718db58e --- /dev/null +++ b/wiki/concepts/QualitySwitch.md @@ -0,0 +1,33 @@ +--- +title: "QualitySwitch" +type: concept +tags: ["unreal-engine", "materials", "performance-optimization", "platform-targeting"] +sources: ["unreal-technical-artist"] +last_updated: 2026-04-26 +--- + +## Definition +UE5 Material Editor 中的 Quality Switch 节点，允许在单一材质图内定义多档质量层级（Mobile / Console / PC），引擎根据目标平台自动选择对应分支。 + +## Quality Tiers +- **High**：PC/主机高端 — 完整着色器逻辑，所有纹理层 +- **Medium**：主机基准/中端 PC — 简化逻辑，较低纹理分辨率 +- **Low**：移动设备/主机性能模式 — 最简化逻辑，单一纹理层 + +## Key Principles +- 在单个材质图中而非多个材质文件中管理质量差异 +- Quality Switch 是架构设计工具，不是性能问题修复工具 +- 必须在所有三档上验证视觉一致性 + +## Relationship to Niagara Scalability +Quality Switch 用于**材质**质量分层，Niagara Scalability 用于**VFX** 质量分层。两者共同构成 UE5 项目的完整质量分级体系。 + +## Shader Complexity Implication +- 每个 Static Switch **使着色器排列数翻倍**（而非加法增加） +- 添加 Static Switch 前必须审计 +- Quality Switch 节点本身不翻倍，但其控制的分支逻辑可能包含 Static Switch + +## Related +- [[NiagaraVFX]] — VFX 系统的 Scalability 分级 +- [[PerformanceBudget]] — Quality Switch 是平台预算管理工具 +- [[MaterialFunction]] — Quality Switch 可封装在 Function 中 diff --git a/wiki/concepts/RPC-Remote-Procedure-Call.md b/wiki/concepts/RPC-Remote-Procedure-Call.md new file mode 100644 index 00000000..e38313b6 --- /dev/null +++ b/wiki/concepts/RPC-Remote-Procedure-Call.md @@ -0,0 +1,59 @@ +--- +title: "RPC (Remote Procedure Call)" +type: concept +tags: [] +sources: [unreal-multiplayer-architect] +last_updated: 2026-04-26 +--- + +## Definition +远程过程调用（RPC）是 UE5 多人游戏中客户端与服务器之间进行通信的核心机制。客户端通过 RPC 向服务器发送请求（Server RPC），服务器通过 RPC 向客户端或所有客户端广播事件（Client RPC / NetMulticast）。 + +## RPC Types +| 类型 | 方向 | 可靠性 | 用途 | +|------|------|--------|------| +| `Server` | 客户端 → 服务器 | Reliable/Unreliable | 客户端请求服务器执行操作 | +| `Client` | 服务器 → 特定客户端 | Reliable/Unreliable | 服务器通知特定客户端 | +| `NetMulticast` | 服务器 → 所有客户端 | Reliable/Unreliable | 服务器广播事件 | + +## Critical Rule: WithValidation +**每个游戏影响型的 Server RPC 必须实现 `_Validate()` 函数。** 缺失 `_Validate()` 构成安全漏洞，恶意客户端可发送非法请求。 + +```cpp +// Server RPC 必须有 WithValidation +UFUNCTION(Server, Reliable, WithValidation) +void ServerRequestInteract(AActor* Target); + +bool AMyActor::ServerRequestInteract_Validate(AActor* Target) +{ + // 拒绝不可能的请求 + if (!IsValid(Target)) return false; + float Distance = FVector::Dist(GetActorLocation(), Target->GetActorLocation()); + return Distance < 200.f; // 最大交互距离 +} + +void AMyActor::ServerRequestInteract_Implementation(AActor* Target) +{ + // 验证通过后安全执行 + PerformInteraction(Target); +} +``` + +## Reliability Guidelines +- **Reliable**：保证按序到达，用于游戏关键事件（伤害、得分、道具拾取） +- **Unreliable**：即发即忘，不保证到达，用于视觉效果、高频位置同步 +- 绝不能将高频调用与可靠 RPC 混合——必须为高频数据创建独立的不可靠更新路径 + +## Connection to Other Concepts +- [[Server-Authoritative Model]] — RPC 是服务器权威执行的游戏请求入口 +- [[Actor Replication]] — 属性复制与 RPC 互补，复制状态、RPC 触发动作 +- [[Network Prediction]] — 客户端在等待服务器 RPC 响应时进行本地预测 + +## Relationship to Agent +[[UnrealMultiplayerArchitect]] 将 RPC 验证视为非妥协原则："Every Server RPC needs a `_Validate`. No exceptions." + +## Aliases +- Remote Procedure Call +- Server RPC +- Client RPC +- NetMulticast diff --git a/wiki/concepts/Replication-Graph.md b/wiki/concepts/Replication-Graph.md new file mode 100644 index 00000000..7ea786c1 --- /dev/null +++ b/wiki/concepts/Replication-Graph.md @@ -0,0 +1,54 @@ +--- +title: "Replication Graph" +type: concept +tags: [unreal-engine, networking, multiplayer, ue5] +sources: [unreal-multiplayer-architect] +last_updated: 2026-04-26 +--- + +## Definition +Replication Graph 是 UE5 的空间分区复制优化系统，用空间网格分区替代默认的扁平相关性模型。通过只向相关客户端复制区域内的 Actor，显著降低带宽消耗。核心机制：`UReplicationGraphNode_GridSpatialization2D`（开放世界空间网格）和自定义 `UReplicationGraphNode`（休眠 Actor 优化）。 + +## Core Mechanisms +- **空间网格分区**：基于 2D 空间网格，将世界划分为网格单元，每个单元仅复制给附近玩家 +- **休眠 Actor 优化**：NPC 等休眠 Actor 不在任何玩家附近时，以极低频率复制 +- **动态 relevancy**：根据客户端视角动态决定 Actor 的相关性 +- `UReplicationGraphNode_GridSpatialization2D`：开放世界空间分区节点 +- `UReplicationGraphNode`：可自定义的复制图节点基类 + +## Implementation +```cpp +// 启用 Replication Graph 插件 +// DefaultEngine.ini +[/Script/OnlineSubsystemUtils.IpNetDriver] +ReplicationGraphClassName=ReplicationGraph.UReplicationGraph + +// 自定义休眠节点 +UCLASS() +class UMyDormancyNode : public UReplicationGraphNode +{ + // 重写 DetermineWrites 会话逻辑 +}; +``` + +## Key Benefits +- 开放世界多人游戏中带宽降低 40%+ +- 仅复制视野内 Actor，减少不必要的网络流量 +- 可自定义节点类型适配特殊需求 + +## Network Profiling Commands +- `net.RepGraph.PrintAllNodes` — 打印所有复制图节点信息 +- Unreal Insights — 性能分析工具，测量复制图对带宽的影响 + +## Connection to Other Concepts +- [[Actor Replication]] — Replication Graph 是 Actor 复制的空间优化层 +- [[Server-Authoritative Model]] — 服务器权威通过复制图高效同步状态到客户端 +- [[Network Prediction]] — 预测系统依赖高效的复制同步 + +## Relationship to Agent +[[UnrealMultiplayerArchitect]] 使用 Replication Graph 作为生产级多人游戏的带宽优化方案，性能基准：\"Bandwidth per player < 15KB/s at maximum player count\"。 + +## Aliases +- UE5 Replication Graph +- Spatial Replication +- Grid Spatialization diff --git a/wiki/concepts/RuntimeVirtualTexturing.md b/wiki/concepts/RuntimeVirtualTexturing.md new file mode 100644 index 00000000..8700c93e --- /dev/null +++ b/wiki/concepts/RuntimeVirtualTexturing.md @@ -0,0 +1,40 @@ +--- +title: "Runtime Virtual Texturing" +type: concept +tags: ["unreal-engine", "landscape", "texturing", "ue5", "performance"] +sources: ["unreal-world-builder", "unreal-technical-artist"] +last_updated: 2026-04-26 +--- + +## Definition +Runtime Virtual Texturing（RVT），UE5 运行时虚拟纹理技术，通过将多层地形纹理混合计算结果缓存到虚拟纹理图集（Virtual Texture Atlas），消除逐像素层混合的 shader 开销。当地形材质层数超过 2 层时，RVT 成为必选项而非可选项。 + +## Core Mechanism +- **Virtual Texture Atlas**：多层混合结果以瓦片（Tile）为单位缓存，按需流送到 GPU +- **RVT Resolution**：通常 2048×2048 每 4096m² 网格单元 +- **RVT Format**：推荐 YCoCg 压缩格式，相比 RGBA 节省内存 +- **Producer**：Landscape Actor 启用 Virtual Texture Producer；需要对应的 RVT Output Volume 放置在世界每个网格单元 + +## When RVT is Required +| 条件 | RVT 建议 | +|------|----------| +| ≤2 层 Landscape 材质 | 可选，性能提升有限 | +| >2 层 Landscape 材质 | **必须启用**，否则产生材质排列组合爆炸 | +| 开放世界（World Partition） | **必须启用**，与流送系统协同 | + +## RVT in Landscape Material Design +典型四层 Landscape 材质结构（配合 RVT）： +1. **Grass**：基础层，始终存在，填充空区域 +2. **Dirt/Path**：沿路径替换草地 +3. **Rock**：坡度驱动（WorldAlignedBlend，斜率阈值 0.6 自动切换） +4. **Snow**：高度驱动（超过 SnowLine 高度参数时淡入） + +Auto-Slope Rock Blend：`dot(WorldUp, SurfaceNormal) < 0.6` → Rock 层渐变到 Grass/Dirt + +## RVT for Dynamic Gameplay State +高级应用：RVT 权重混合可采样 Gameplay Tags 或 Decal Actor，驱动动态地形状态变化（如降雨累积 → 湿滑表面层）。 + +## Related +- [[UnrealWorldBuilder]] — RVT 配置与调优专家 +- [[UnrealTechnicalArtist]] — Landscape Master Material 构建与 RVT Output Volume 放置 +- [[Landscape]] — RVT 是 Landscape 材质系统的性能关键 diff --git a/wiki/concepts/Server-Authoritative-Model.md b/wiki/concepts/Server-Authoritative-Model.md new file mode 100644 index 00000000..c1c1a04c --- /dev/null +++ b/wiki/concepts/Server-Authoritative-Model.md @@ -0,0 +1,41 @@ +--- +title: "Server-Authoritative Model" +type: concept +tags: [] +sources: [unreal-multiplayer-architect] +last_updated: 2026-04-26 +--- + +## Definition +服务器权威模型是 UE5 多人游戏网络架构的核心原则：服务器拥有真相（Server Owns Truth），所有游戏状态变更必须在服务器执行，客户端仅发送请求（RPC），由服务器验证后复制结果。 + +## Core Principles +- 所有游戏逻辑和状态变更必须运行在服务器端 +- 客户端仅负责输入发送、本地预测和视觉表现 +- `HasAuthority()` 检查必须在每次状态变更前执行 +- 服务器有权拒绝任何非法客户端请求 + +## Implementation in UE5 +```cpp +void AMyCharacter::TakeDamage(float DamageAmount) +{ + // 必须先检查权威 + if (!HasAuthority()) return; // 客户端绝对不能直接修改生命值 + + Health -= DamageAmount; + // 服务器修改后自动复制到所有客户端 +} +``` + +## Connection to Other Concepts +- [[Actor Replication]] — 实现服务器权威的具体机制 +- [[Network Prediction]] — 客户端利用权威模型进行本地预测以减少延迟 +- [[RPC (Remote Procedure Call)]] — 客户端向服务器发送请求的通信方式 + +## Relationship to Agent +[[UnrealMultiplayerArchitect]] 是该模型的严格执行者，其核心规则强制所有游戏状态变更必须通过服务器权威验证。 + +## Aliases +- Server Authority +- Server-Owns-Truth +- Server-Authoritative Networking diff --git a/wiki/concepts/ServerAuthority.md b/wiki/concepts/ServerAuthority.md new file mode 100644 index 00000000..d959b9c5 --- /dev/null +++ b/wiki/concepts/ServerAuthority.md @@ -0,0 +1,37 @@ +--- +title: "Server Authority" +type: concept +tags: [networking, multiplayer, security] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- Server Authority Model +- Server-Authoritative Architecture + +## Definition +服务器权威模型是一种多人游戏网络架构范式，其中**服务器拥有所有游戏状态的最终真相**，包括玩家位置、生命值、分数、物品所有权等。客户端仅发送输入请求，服务器模拟并广播权威状态给所有客户端。 + +## Key Principles +- 客户端**永远不直接发送位置数据**——只发送原始输入（方向键、鼠标点击等） +- 服务器执行所有游戏逻辑模拟，客户端显示服务器返回的结果 +- **"永远不要信任来自客户端未经服务器验证的值"** +- 客户端预测移动后必须与服务器状态调和校正 + +## Implementation in Unity (NGO) +```csharp +// 服务器权威位置（只有服务器可写） +private NetworkVariable _serverPosition = new NetworkVariable( + readPerm: NetworkVariableReadPermission.Everyone, + writePerm: NetworkVariableWritePermission.Server); +``` + +## Related Concepts +- [[ClientPrediction]]: 客户端预测在服务器权威框架下的实现 +- [[LagCompensation]]: 延迟补偿依赖服务器权威 +- [[AntiCheatArchitecture]]: 服务器权威是反作弊的基础 + +## Related Entities +- [[UnityMultiplayerEngineer]]: 实现服务器权威的专家角色 +- [[UnrealMultiplayerArchitect]]: 虚幻引擎中的对应角色 diff --git a/wiki/concepts/Substrate.md b/wiki/concepts/Substrate.md new file mode 100644 index 00000000..cd63f607 --- /dev/null +++ b/wiki/concepts/Substrate.md @@ -0,0 +1,39 @@ +--- +title: "Substrate" +type: concept +tags: ["unreal-engine", "materials", "shader", "ue5.3"] +sources: ["unreal-technical-artist"] +last_updated: 2026-04-26 +--- + +## Definition +UE5.3+ 引入的多层物理材质系统（Multi-Layer Physical Material System）。通过显式层叠堆栈（Slab）定义材质：湿涂层（wet coat）→ 泥土（dirt）→ 岩石（rock）。物理正确，性能可控，替代了传统的 Subsurface Scattering（SSS）workaround。 + +## Architecture +Substrate 将材质建模为多层 slab 的堆叠： +- 每层有独立的 BSDF（双向散射分布函数） +- 层间有物理模拟的界面交互（界面反射、透射） +- 与真实世界的多层材质（油漆→底漆→金属基底）对应 + +## Migration Path +从旧版 Shading Model 系统迁移到 Substrate： +1. 分析现有材质的视觉层（表层污垢、中层基础颜色、底层金属/次表面） +2. 映射为 Substrate slab 堆叠顺序 +3. 使用 Substrate Complexity viewport mode 验证复杂度 +4. 在目标平台（尤其主机）上 Profile 性能 + +## Advantages over Legacy SSS +- 物理正确性：多层交互有真实光学模型支撑 +- 单一材质：无需多个材质叠加 +- 性能可控：Substrate Complexity 工具可精确测量 +- 适用场景：湿表面、雪地、积雪岩石、多层植被 + +## Compatibility +- UE 5.3+ 可用 +- 主机平台需要额外验证 +- 与 Nanite 兼容 + +## Related +- [[MaterialFunction]] — Substrate slab 逻辑可封装为 Function +- [[VFX]] — Substrate 用于静态场景材质，与 VFX 系统的物理真实感追求一致 +- [[QualitySwitch]] — Substrate 也需要质量分级 diff --git a/wiki/concepts/UnityLobby.md b/wiki/concepts/UnityLobby.md new file mode 100644 index 00000000..dbe7dd69 --- /dev/null +++ b/wiki/concepts/UnityLobby.md @@ -0,0 +1,39 @@ +--- +title: "Unity Lobby" +type: concept +tags: [networking, unity, ugs, matchmaking] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- Unity Gaming Services Lobby +- UGS Lobby +- Unity Matchmaking Lobby + +## Definition +Unity Lobby 是 Unity Gaming Services（UGS）提供的**匹配大厅服务**，允许玩家创建和加入游戏房间。Lobby 仅存储元数据（如房间名、地图选择、玩家就绪状态），不存储游戏状态。 + +## Data Storage Rules +| 数据类型 | 示例 | 存储位置 | +|----------|------|----------| +| 元数据 | 房间名、地图、游戏模式 | Lobby Data | +| 玩家状态 | 名称、就绪、皮肤选择 | Lobby Data / Player Data | +| **游戏状态** | 生命值、位置、分数 | **禁止存储在 Lobby** | + +## Visibility Options +- `Visibility.Public`: 对所有玩家可见 +- `Visibility.Member`: 仅房间内成员可见 +- `Visibility.Private`: 仅指定玩家可见 + +## Heartbeat Requirement +Lobby 默认 30 秒无心跳自动销毁，需客户端定期调用 `SendHeartbeatPingAsync`（建议每 15 秒）。 + +## Related Concepts +- [[UnityRelay]]: 与 Relay 配合，Relay 处理网络连接，Lobby 处理匹配 +- [[AntiCheatArchitecture]]: Lobby 不应存储游戏状态，防止数据泄露 +- [[UnityGamingServices]]: Lobby 是 UGS 的核心组件 + +## Related Entities +- [[UnityGamingServices]]: Lobby 所属的服务平台 +- [[UnityMultiplayerEngineer]]: 配置和使用 Lobby 的专家角色 diff --git a/wiki/concepts/UnityRelay.md b/wiki/concepts/UnityRelay.md new file mode 100644 index 00000000..af4eda91 --- /dev/null +++ b/wiki/concepts/UnityRelay.md @@ -0,0 +1,38 @@ +--- +title: "Unity Relay" +type: concept +tags: [networking, unity, ugs, nat-traversal] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- Unity Gaming Services Relay +- UGS Relay + +## Definition +Unity Relay 是 Unity Gaming Services（UGS）提供的**流量中继服务**，用于解决 NAT 穿透问题，使不同网络环境下的玩家能够建立连接。玩家托管游戏必须使用 Relay，直接 P2P 连接会暴露主机 IP 地址。 + +## Key Features +- **无需专用服务器**：玩家之一作为 Host，其他玩家通过 Relay 连接 +- **IP 保护**：Relay 隐藏了 Host 的真实 IP 地址 +- **多平台兼容**：支持 UDP/TCP DTLS 加密传输 + +## Workflow +1. Host 初始化 Unity Services + 匿名认证 +2. Host 创建 Relay Allocation，获取 Join Code +3. Host 将 Join Code 分享给其他玩家 +4. Clients 通过 Join Code 加入 Relay +5. UnityTransport 自动将流量路由至 Relay 服务器 + +## Security Note +> "Always use Relay for player-hosted games — direct P2P exposes host IP addresses" + +## Related Concepts +- [[UnityLobby]]: 与 Lobby 配合实现完整匹配流程 +- [[ServerAuthority]]: Relay 使服务器权威模型在玩家托管游戏中可行 +- [[UnityGamingServices]]: Relay 是 UGS 的核心组件之一 + +## Related Entities +- [[UnityGamingServices]]: Relay 所属的服务平台 +- [[UnityMultiplayerEngineer]]: 使用 Relay 构建多人游戏的专家 diff --git a/wiki/concepts/WorldPartition.md b/wiki/concepts/WorldPartition.md new file mode 100644 index 00000000..cc13b809 --- /dev/null +++ b/wiki/concepts/WorldPartition.md @@ -0,0 +1,41 @@ +--- +title: "World Partition" +type: concept +tags: ["unreal-engine", "open-world", "streaming", "ue5"] +sources: ["unreal-world-builder", "unreal-technical-artist"] +last_updated: 2026-04-26 +--- + +## Definition +UE5 的开放世界分区管理框架，将世界划分为网格状单元格（Cell），支持按需流送（on-demand streaming），使超大世界无需一次性全部加载到内存。 + +## Core Concepts + +### Grid Cell Sizes +| 内容类型 | 格子大小 | 加载范围 | +|----------|----------|----------| +| 密集城区 | 64m | 256m | +| 空旷地形 | 128m | 512m | +| 稀疏区域（沙漠/海洋） | 256m+ | 1024m+ | + +### Critical Rules +- **格子大小由流送预算决定**：小格子 = 更细粒度流送但更多开销 +- **关键游戏内容禁止放在格子边界**：格子跨越时流送短暂延迟可能导致关键 NPC/任务触发器不可见 +- **Always Loaded 层**：Sky、Audio Manager、GameMode 等全局内容必须放入 Always Loaded 数据层，不能分散在流送格子中 +- **Runtime Hash Grid 配置必须在填充世界前完成**：后期修改需完整重保存关卡 + +### Streaming Sources +- **Player Pawn**：主要流送源，激活范围 = 加载范围 +- **Cinematic Camera**：辅助流送源，用于过场动画区域预加载 +- **非玩家流送源**：通过 `AWorldPartitionStreamingSourceComponent` 实现，供 AI Director、过场系统使用 + +## OFPA (One File Per Actor) +- 为多用户协作启用 OFPA：避免多人同时编辑同一关卡文件产生的冲突 +- 大型关卡包含数千 Actor，会生成数千个文件，需建立文件数量预算 + +## Related +- [[UnrealWorldBuilder]] — World Partition 配置与调优专家 +- [[PCG]] — PCG 图与 World Partition Surface 协同工作 +- [[HLOD]] — World Partition 与 HLOD 系统深度集成 +- [[LOD]] — HLOD 是 World Partition 远距离渲染优化的核心机制 +- [[Nanite]] — World Partition 流送加载区域的 Nanite 几何体优化 diff --git a/wiki/entities/NetcodeForGameObjects.md b/wiki/entities/NetcodeForGameObjects.md new file mode 100644 index 00000000..5f29a9d2 --- /dev/null +++ b/wiki/entities/NetcodeForGameObjects.md @@ -0,0 +1,43 @@ +--- +title: "Netcode for GameObjects" +type: entity +tags: [unity, networking, framework] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- NGO +- Netcode for GameObjects (NGO) + +## Type +Unity 官方多人游戏网络框架 + +## Definition +Netcode for GameObjects（NGO）是 Unity 官方提供的多人游戏网络编程框架，提供 `NetworkObject`、`NetworkVariable`、`ServerRpc`、`ClientRpc` 等核心网络原语，简化服务器权威多人游戏开发。 + +## Core Components + +| 组件 | 类型 | 用途 | +|------|------|------| +| `NetworkObject` | 组件 | 挂载到 GameObject 使其可联网 | +| `NetworkVariable` | 类型 | 持久化状态同步 | +| `ServerRpc` | 特性 | 客户端调用 → 服务器执行 | +| `ClientRpc` | 特性 | 服务器调用 → 所有客户端执行 | +| `NetworkManager` | 组件 | 网络管理器 | +| `UnityTransport` | 组件 | 底层传输层（支持直连/Relay） | + +## Key Design Decisions +- **服务器权威**：所有 NetworkVariable write 权限默认为 Server +- **自动同步**：NetworkVariable 变化自动同步，无需手动调用 +- **Prefabs 注册**：所有联网 Prefab 必须注册到 NetworkPrefabs 列表 + +## Related Concepts +- [[ServerAuthority]]: NGO 强制服务器权威 +- [[NetworkVariable]]: 核心数据类型 +- [[UnityRelay]]: 通过 UnityTransport 集成 Relay +- [[UnityMultiplayerEngineer]]: 使用 NGO 构建游戏的专家 + +## Related Entities +- [[UnityGamingServices]]: NGO 与 UGS 深度集成 +- [[UnityTransport]]: NGO 的传输层实现 diff --git a/wiki/entities/UnityGamingServices.md b/wiki/entities/UnityGamingServices.md new file mode 100644 index 00000000..c31da596 --- /dev/null +++ b/wiki/entities/UnityGamingServices.md @@ -0,0 +1,42 @@ +--- +title: "Unity Gaming Services" +type: entity +tags: [unity, cloud-services, platform] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- UGS +- Unity Cloud Services + +## Type +Unity 云服务平台 + +## Definition +Unity Gaming Services（UGS）是 Unity 官方提供的云服务集合，包含身份认证、匹配大厅、流量中继、分析、远程配置等多人游戏所需的云端组件。 + +## Core Services for Multiplayer + +| 服务 | 用途 | +|------|------| +| **Relay** | 流量中继，解决 NAT 穿透，保护主机 IP | +| **Lobby** | 匹配大厅，存储元数据（房间名、地图等） | +| **Authentication** | 匿名登录，为 Relay/Lobby 提供玩家身份 | +| **Multiplay** | 专业服务器托管（付费服务） | + +## Quick Start +```csharp +await UnityServices.InitializeAsync(); +await AuthenticationService.Instance.SignInAnonymouslyAsync(); +``` + +## Related Concepts +- [[UnityRelay]]: UGS 核心多人服务 +- [[UnityLobby]]: UGS 核心多人服务 +- [[ServerAuthority]]: UGS 服务支持服务器权威架构 + +## Related Entities +- [[UnityMultiplayerEngineer]]: 使用 UGS 的专家 +- [[UnityTransport]]: 集成 UGS 服务的传输层 +- [[UnityGamingServices]]: 即本条目 diff --git a/wiki/entities/UnityMultiplayerEngineer.md b/wiki/entities/UnityMultiplayerEngineer.md new file mode 100644 index 00000000..0982456e --- /dev/null +++ b/wiki/entities/UnityMultiplayerEngineer.md @@ -0,0 +1,45 @@ +--- +title: "Unity Multiplayer Engineer" +type: entity +tags: [agent, unity, networking] +sources: [unity-multiplayer-engineer] +last_updated: 2026-04-26 +--- + +## Aliases +- UnityMultiplayerEngineer + +## Type +AI Agent 人格角色定义 + +## Definition +Unity Multiplayer Engineer 是一个 AI Agent 人格定义，专门用于设计和实现 Unity 多人游戏网络系统。角色具备延迟感知、抗作弊意识、确定性思维，专注于服务器权威、客户端预测和带宽优化。 + +## Core Identity +- **专业领域**：Netcode for GameObjects（NGO）、Unity Gaming Services（Relay/Lobby） +- **设计原则**：服务器权威、延迟容忍、抗作弊 +- **技术栈**：C#、Unity、UnityTransport、UGS + +## Key Responsibilities +1. 实现服务器权威游戏逻辑 +2. 集成 Unity Relay 和 Lobby +3. 设计 NetworkVariable 和 RPC 架构 +4. 实现客户端预测与调和 +5. 构建反作弊验证系统 + +## Success Metrics +- 200ms 模拟延迟下零同步错误 +- 所有 ServerRpc 输入经服务器验证 +- 每玩家稳态带宽 < 10KB/s +- Relay 连接成功率 > 98% + +## Related Concepts +- [[ServerAuthority]]: 角色遵循的核心架构 +- [[ClientPrediction]]: 角色实现的关键技术 +- [[AntiCheatArchitecture]]: 角色的核心职责之一 +- [[BandwidthManagement]]: 角色的性能优化目标 + +## Related Entities +- [[UnrealMultiplayerArchitect]]: 虚幻引擎领域的对应角色 +- [[NetcodeForGameObjects]]: 角色的主要工具 +- [[UnityGamingServices]]: 角色依赖的云服务 diff --git a/wiki/entities/UnrealEngine5.md b/wiki/entities/UnrealEngine5.md new file mode 100644 index 00000000..570ecfc5 --- /dev/null +++ b/wiki/entities/UnrealEngine5.md @@ -0,0 +1,24 @@ +--- +title: "Unreal Engine 5" +type: entity +tags: ["game-engine", "game-development", "unreal"] +sources: ["unreal-technical-artist", "unreal-world-builder"] +last_updated: 2026-04-26 +--- + +## Overview +Unreal Engine 5（UE5）是 Epic Games 开发的新一代游戏引擎，提供完整的 AAA 级视觉内容创作工具链。[[unreal-technical-artist]] 的核心工作平台。 + +## Key Capabilities Relevant to Technical Art +- **Material Editor**：可视化材质创作系统，支持 Material Functions、Material Instances、Quality Switch +- **Niagara**：新一代 VFX 和粒子系统，支持 GPU/CPU 分离模拟 +- **PCG**（Procedural Content Generation）：程序化内容生成框架，用于开放世界资产分布 +- **Nanite**：虚拟几何体系统，支持自动 LOD 和海量实例化 +- **Substrate**（UE5.3+）：多层物理材质系统，替代传统 SSS workaround +- **World Partition**：开放世界分区管理，与 HLOD 和 PCG 流式加载协同 +- **Unreal Insights**：性能分析工具，用于渲染性能瓶颈诊断 + +## In This Wiki +- [[unreal-technical-artist]] — 视觉系统工程师 Agent，依赖 UE5 工具链交付 AAA 视觉资产 +- [[unreal-world-builder]] — 开放世界场景搭建 Agent，基于 UE5 World Partition +- [[unreal-systems-engineer]] — 引擎底层系统工程师 Agent，深度集成 UE5 架构 diff --git a/wiki/entities/UnrealMultiplayerArchitect.md b/wiki/entities/UnrealMultiplayerArchitect.md new file mode 100644 index 00000000..8bfc202e --- /dev/null +++ b/wiki/entities/UnrealMultiplayerArchitect.md @@ -0,0 +1,33 @@ +--- +title: "Unreal Multiplayer Architect" +type: entity +tags: [agent, unreal, networking] +sources: [unreal-multiplayer-architect] +last_updated: 2026-04-26 +--- + +## Aliases +- UnrealMultiplayerArchitect + +## Type +AI Agent 人格角色定义 + +## Definition +Unreal Multiplayer Architect 是一个 AI Agent 人格定义，专门用于设计和实现 Unreal Engine 多人游戏系统。角色专注于 GAS（Gameplay Ability System）、Gameplay Tags、网络角色所有权和 RPC 设计。 + +## Core Identity +- **专业领域**：Unreal Engine 5、Gameplay Framework、GAS、Replication +- **设计原则**：服务器权威、网络优化、确定性多人游戏 +- **技术栈**：C++、Blueprints、Unreal Networking + +## Related Concepts +- [[ServerAuthority]]: 角色遵循的核心架构（与 Unity 版本互补） +- [[LagCompensation]]: 角色实现的关键技术 + +## Related Entities +- [[UnityMultiplayerEngineer]]: Unity 引擎领域的对应角色 + +## Connections to Unity Side +- 两者在 [[ServerAuthority]] 原则上完全一致 +- 客户端预测实现细节有差异，可互补学习 +- 网络框架不同，但架构模式相通 diff --git a/wiki/index.md b/wiki/index.md index aa263896..cd411426 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -4,6 +4,22 @@ - [Overview](overview.md) — living synthesis ## Sources +- [2026-04-26] [Software Architect Agent Personality](sources/engineering-software-architect.md) +- [2026-04-26] [Godot Multiplayer Engineer Agent Personality](sources/godot-multiplayer-engineer.md) +- [2026-04-26] [Godot Shader Developer Agent Personality](sources/godot-shader-developer.md) +- [2026-04-26] [Godot Gameplay Scripter Agent Personality](sources/godot-gameplay-scripter.md) +- [2026-04-26] [Blender Add-on Engineer Agent Personality](sources/blender-addon-engineer.md) +- [2026-04-26] [Roblox Avatar Creator Agent Personality](sources/roblox-avatar-creator.md) +- [2026-04-26] [Roblox Systems Scripter Agent Personality](sources/roblox-systems-scripter.md) +- [2026-04-26] [Roblox Experience Designer](sources/roblox-experience-designer.md) +- [2026-04-26] [Unity Architect](sources/unity-architect.md) +- [2026-04-26] [Unity Multiplayer Engineer](sources/unity-multiplayer-engineer.md) +- [2026-04-26] [Unity Shader Graph Artist](sources/unity-shader-graph-artist.md) +- [2026-04-26] [Unity Editor Tool Developer](sources/unity-editor-tool-developer.md) +- [2026-04-26] [Unreal World Builder Agent Personality](sources/unreal-world-builder.md) +- [2026-04-26] [Unreal Systems Engineer](sources/unreal-systems-engineer.md) +- [2026-04-26] [Unreal Multiplayer Architect](sources/unreal-multiplayer-architect.md) +- [2026-04-26] [Unreal Technical Artist](sources/unreal-technical-artist.md) - [2026-04-26] [Game Designer Agent Personality](sources/game-designer.md) - [2026-04-25] [Narrative Designer Agent Personality](sources/narrative-designer.md) - [2026-04-25] [Level Designer Agent Personality](sources/level-designer.md) @@ -490,22 +506,6 @@ - [agent-activation-prompts](sources/agent-activation-prompts.md) — (expected: wiki/sources/agent-activation-prompts.md — source missing) - [quickstart](sources/quickstart.md) — (expected: wiki/sources/quickstart.md — source missing) - [executive-brief](sources/executive-brief.md) — (expected: wiki/sources/executive-brief.md — source missing) -- [unreal-world-builder](sources/unreal-world-builder.md) — (expected: wiki/sources/unreal-world-builder.md — source missing) -- [unreal-technical-artist](sources/unreal-technical-artist.md) — (expected: wiki/sources/unreal-technical-artist.md — source missing) -- [unreal-systems-engineer](sources/unreal-systems-engineer.md) — (expected: wiki/sources/unreal-systems-engineer.md — source missing) -- [unreal-multiplayer-architect](sources/unreal-multiplayer-architect.md) — (expected: wiki/sources/unreal-multiplayer-architect.md — source missing) -- [unity-shader-graph-artist](sources/unity-shader-graph-artist.md) — (expected: wiki/sources/unity-shader-graph-artist.md — source missing) -- [unity-multiplayer-engineer](sources/unity-multiplayer-engineer.md) — (expected: wiki/sources/unity-multiplayer-engineer.md — source missing) -- [unity-editor-tool-developer](sources/unity-editor-tool-developer.md) — (expected: wiki/sources/unity-editor-tool-developer.md — source missing) -- [unity-architect](sources/unity-architect.md) — (expected: wiki/sources/unity-architect.md — source missing) -- [roblox-systems-scripter](sources/roblox-systems-scripter.md) — (expected: wiki/sources/roblox-systems-scripter.md — source missing) -- [roblox-experience-designer](sources/roblox-experience-designer.md) — (expected: wiki/sources/roblox-experience-designer.md — source missing) -- [roblox-avatar-creator](sources/roblox-avatar-creator.md) — (expected: wiki/sources/roblox-avatar-creator.md — source missing) -- [godot-shader-developer](sources/godot-shader-developer.md) — (expected: wiki/sources/godot-shader-developer.md — source missing) -- [godot-multiplayer-engineer](sources/godot-multiplayer-engineer.md) — (expected: wiki/sources/godot-multiplayer-engineer.md — source missing) -- [godot-gameplay-scripter](sources/godot-gameplay-scripter.md) — (expected: wiki/sources/godot-gameplay-scripter.md — source missing) -- [game-designer](sources/game-designer.md) — (expected: wiki/sources/game-designer.md — source missing) -- [blender-addon-engineer](sources/blender-addon-engineer.md) — (expected: wiki/sources/blender-addon-engineer.md — source missing) - [engineering-wechat-mini-program-developer](sources/engineering-wechat-mini-program-developer.md) — (expected: wiki/sources/engineering-wechat-mini-program-developer.md — source missing) - [engineering-threat-detection-engineer](sources/engineering-threat-detection-engineer.md) — (expected: wiki/sources/engineering-threat-detection-engineer.md — source missing) - [engineering-technical-writer](sources/engineering-technical-writer.md) — (expected: wiki/sources/engineering-technical-writer.md — source missing) @@ -721,6 +721,7 @@ - [Nano Banana 2](entities/Nano Banana 2.md) - [Navidrome](entities/Navidrome.md) - [NetApp](entities/NetApp.md) +- [NetcodeForGameObjects](entities/NetcodeForGameObjects.md) - [Netdata](entities/Netdata.md) - [Nexus-Spatial](entities/Nexus-Spatial.md) - [NicholasCarlini](entities/NicholasCarlini.md) @@ -808,6 +809,10 @@ - [TypeScript-Language-Server](entities/TypeScript-Language-Server.md) - [Ubuntu-Server](entities/Ubuntu-Server.md) - [UI-Designer](entities/UI-Designer.md) +- [UnityGamingServices](entities/UnityGamingServices.md) +- [UnityMultiplayerEngineer](entities/UnityMultiplayerEngineer.md) +- [UnrealEngine5](entities/UnrealEngine5.md) +- [UnrealMultiplayerArchitect](entities/UnrealMultiplayerArchitect.md) - [Upload-Post](entities/Upload-Post.md) - [Uptime-Kuma](entities/Uptime-Kuma.md) - [UX-Researcher](entities/UX-Researcher.md) @@ -854,6 +859,7 @@ - [AccountArchitecture](concepts/AccountArchitecture.md) - [ActionItemTracking](concepts/ActionItemTracking.md) - [Active-Accountability](concepts/Active-Accountability.md) +- [Actor-Replication](concepts/Actor-Replication.md) - [Adaptive-Tone](concepts/Adaptive-Tone.md) - [AdaptiveMusic](concepts/AdaptiveMusic.md) - [ADDIE-Model](concepts/ADDIE-Model.md) @@ -896,6 +902,7 @@ - [Analytics-Feedback-Loop](concepts/Analytics-Feedback-Loop.md) - [Annales-School](concepts/Annales-School.md) - [Answer-Engine-Optimization](concepts/Answer-Engine-Optimization.md) +- [AntiCheatArchitecture](concepts/AntiCheatArchitecture.md) - [Appearance-Anxiety](concepts/Appearance-Anxiety.md) - [APT-仓库配置](concepts/APT-仓库配置.md) - [Architectural-Empathy](concepts/Architectural-Empathy.md) @@ -918,6 +925,7 @@ - [B2B-Social-Selling](concepts/B2B-Social-Selling.md) - [Baidu-Ecosystem-Integration](concepts/Baidu-Ecosystem-Integration.md) - [Baidu-SEO](concepts/Baidu-SEO.md) +- [BandwidthManagement](concepts/BandwidthManagement.md) - [Beat-Sync](concepts/Beat-Sync.md) - [BEATS](concepts/BEATS.md) - [Behavioral-Psychology](concepts/Behavioral-Psychology.md) @@ -968,6 +976,7 @@ - [Claude-Code-Templates](concepts/Claude-Code-Templates.md) - [Claude-Skills](concepts/Claude-Skills.md) - [Claudian](concepts/Claudian.md) +- [ClientPrediction](concepts/ClientPrediction.md) - [Cloud-Adoption-Strategy](concepts/Cloud-Adoption-Strategy.md) - [Cloud-Cost-Optimization](concepts/Cloud-Cost-Optimization.md) - [Cloud-DevOps-Maturity-Model](concepts/Cloud-DevOps-Maturity-Model.md) @@ -1017,6 +1026,7 @@ - [Continuous-Integration](concepts/Continuous-Integration.md) - [Conversational-Interface](concepts/Conversational-Interface.md) - [Conversions-API](concepts/Conversions-API.md) +- [Core-Gameplay-Loop](concepts/Core-Gameplay-Loop.md) - [Cost-Optimization](concepts/Cost-Optimization.md) - [CoworkWorkspace](concepts/CoworkWorkspace.md) - [Coze-Workflow](concepts/Coze-Workflow.md) @@ -1078,6 +1088,7 @@ - [Earnings-Beat-Miss](concepts/Earnings-Beat-Miss.md) - [Earnings-Calendar](concepts/Earnings-Calendar.md) - [EC2-Purchase-Options](concepts/EC2-Purchase-Options.md) +- [Economy-Balance](concepts/Economy-Balance.md) - [efibootmgr](concepts/efibootmgr.md) - [EFS-vs-EBS](concepts/EFS-vs-EBS.md) - [EKS-Auto-Mode](concepts/EKS-Auto-Mode.md) @@ -1124,6 +1135,7 @@ - [Full-Funnel-Campaign-Architecture](concepts/Full-Funnel-Campaign-Architecture.md) - [Fuzzy-Matching](concepts/Fuzzy-Matching.md) - [Gamification](concepts/Gamification.md) +- [GAS-Gameplay-Ability-System](concepts/GAS-Gameplay-Ability-System.md) - [Gatekeeper](concepts/Gatekeeper.md) - [GDM3](concepts/GDM3.md) - [Gegenrede](concepts/Gegenrede.md) @@ -1208,11 +1220,13 @@ - [Knowledge-Base-RAG](concepts/Knowledge-Base-RAG.md) - [Kolb-体验式学习圈](concepts/Kolb-体验式学习圈.md) - [Kubernetes](concepts/Kubernetes.md) +- [LagCompensation](concepts/LagCompensation.md) - [Land-and-Expand](concepts/Land-and-Expand.md) - [Landing-Zone-Architecture](concepts/Landing-Zone-Architecture.md) - [LangChain](concepts/LangChain.md) - [Language-Detection](concepts/Language-Detection.md) - [Large-Language-Model](concepts/Large-Language-Model.md) +- [LargeWorldCoordinates](concepts/LargeWorldCoordinates.md) - [Last-30-Days-Method](concepts/Last-30-Days-Method.md) - [LaTeX-Flattening](concepts/LaTeX-Flattening.md) - [launchd](concepts/launchd.md) @@ -1229,6 +1243,7 @@ - [Local-first-Git](concepts/Local-first-Git.md) - [Local-LLM-Deployment](concepts/Local-LLM-Deployment.md) - [Lockable-Workflow](concepts/Lockable-Workflow.md) +- [LOD](concepts/LOD.md) - [LOD-Pipeline](concepts/LOD-Pipeline.md) - [Log-Driven-Debugging](concepts/Log-Driven-Debugging.md) - [Longue-Duree](concepts/Longue-Duree.md) @@ -1239,6 +1254,7 @@ - [Mackinder-Heartland-Theory](concepts/Mackinder-Heartland-Theory.md) - [Management-Pack](concepts/Management-Pack.md) - [Marketing-Attribution](concepts/Marketing-Attribution.md) +- [MaterialFunction](concepts/MaterialFunction.md) - [MCPOnceAllAgents](concepts/MCPOnceAllAgents.md) - [MEDDPICC](concepts/MEDDPICC.md) - [Medical-Advertisement-Review](concepts/Medical-Advertisement-Review.md) @@ -1272,6 +1288,7 @@ - [Multi-Tenancy](concepts/Multi-Tenancy.md) - [Multi-Window-Architecture](concepts/Multi-Window-Architecture.md) - [N8nWorkflowStandard](concepts/N8nWorkflowStandard.md) +- [Nanite](concepts/Nanite.md) - [Narrative-Debt](concepts/Narrative-Debt.md) - [Narrative-Debt-Tracking](concepts/Narrative-Debt-Tracking.md) - [Narrative-Gameplay-Integration](concepts/Narrative-Gameplay-Integration.md) @@ -1279,7 +1296,10 @@ - [National-Annex](concepts/National-Annex.md) - [NegativePromptingLibrary](concepts/NegativePromptingLibrary.md) - [Net-Revenue-Retention](concepts/Net-Revenue-Retention.md) +- [Network-Prediction](concepts/Network-Prediction.md) +- [NetworkVariable](concepts/NetworkVariable.md) - [NFS网络备份](concepts/NFS网络备份.md) +- [NiagaraVFX](concepts/NiagaraVFX.md) - [Nitro-System](concepts/Nitro-System.md) - [Normal-Change](concepts/Normal-Change.md) - [NorthStarMetric](concepts/NorthStarMetric.md) @@ -1306,6 +1326,7 @@ - [passkey](concepts/passkey.md) - [Patient-Privacy-PIPL](concepts/Patient-Privacy-PIPL.md) - [Pay-as-you-go](concepts/Pay-as-you-go.md) +- [PCG](concepts/PCG.md) - [Peer-Verification](concepts/Peer-Verification.md) - [Penetration-Testing](concepts/Penetration-Testing.md) - [Performance-Budget](concepts/Performance-Budget.md) @@ -1354,6 +1375,7 @@ - [Quality-Gate](concepts/Quality-Gate.md) - [Quality-Scoring-Algorithm](concepts/Quality-Scoring-Algorithm.md) - [QualityAdjustedCoverage](concepts/QualityAdjustedCoverage.md) +- [QualitySwitch](concepts/QualitySwitch.md) - [RAG](concepts/RAG.md) - [Reality-Signal](concepts/Reality-Signal.md) - [RealityKit-SwiftUI-Integration](concepts/RealityKit-SwiftUI-Integration.md) @@ -1373,6 +1395,7 @@ - [RemoteDevelopment](concepts/RemoteDevelopment.md) - [RemoteRescuePattern](concepts/RemoteRescuePattern.md) - [Renovate-Bot](concepts/Renovate-Bot.md) +- [Replication-Graph](concepts/Replication-Graph.md) - [Resource-Allocation](concepts/Resource-Allocation.md) - [ResponsiveSearchAds](concepts/ResponsiveSearchAds.md) - [Retrieval](concepts/Retrieval.md) @@ -1383,9 +1406,11 @@ - [ROI](concepts/ROI.md) - [Rollback-Rate](concepts/Rollback-Rate.md) - [Root-Cause-Analysis](concepts/Root-Cause-Analysis.md) +- [RPC-Remote-Procedure-Call](concepts/RPC-Remote-Procedure-Call.md) - [RPO](concepts/RPO.md) - [RSS-Aggregation](concepts/RSS-Aggregation.md) - [RTO](concepts/RTO.md) +- [RuntimeVirtualTexturing](concepts/RuntimeVirtualTexturing.md) - [S3-兼容对象存储](concepts/S3-兼容对象存储.md) - [Safeguard-Steps](concepts/Safeguard-Steps.md) - [Sandboxed-Persona](concepts/Sandboxed-Persona.md) @@ -1417,6 +1442,8 @@ - [Semantic-Zoom](concepts/Semantic-Zoom.md) - [Sequential-Handoff](concepts/Sequential-Handoff.md) - [Sequential-Thinking](concepts/Sequential-Thinking.md) +- [Server-Authoritative-Model](concepts/Server-Authoritative-Model.md) +- [ServerAuthority](concepts/ServerAuthority.md) - [Serverless-Computing](concepts/Serverless-Computing.md) - [Service-Control-Policies-SCPs](concepts/Service-Control-Policies-SCPs.md) - [SES-Sandbox-Mode](concepts/SES-Sandbox-Mode.md) @@ -1465,6 +1492,7 @@ - [StructuredInterview](concepts/StructuredInterview.md) - [StudyVault](concepts/StudyVault.md) - [Sub-Agent-Race-Condition](concepts/Sub-Agent-Race-Condition.md) +- [Substrate](concepts/Substrate.md) - [SwiftUI-Volumetric-APIs](concepts/SwiftUI-Volumetric-APIs.md) - [symbolic-link](concepts/symbolic-link.md) - [System-Economy](concepts/System-Economy.md) @@ -1514,6 +1542,8 @@ - [UEFI启动](concepts/UEFI启动.md) - [ULS](concepts/ULS.md) - [Unified-Inbox](concepts/Unified-Inbox.md) +- [UnityLobby](concepts/UnityLobby.md) +- [UnityRelay](concepts/UnityRelay.md) - [USER.md](concepts/USER.md.md) - [Value-Stream-Mapping](concepts/Value-Stream-Mapping.md) - [Variables-YAML](concepts/Variables-YAML.md) @@ -1545,6 +1575,7 @@ - [Workflow-Registry](concepts/Workflow-Registry.md) - [Workflow-Tree-Spec](concepts/Workflow-Tree-Spec.md) - [Workspace](concepts/Workspace.md) +- [WorldPartition](concepts/WorldPartition.md) - [X11](concepts/X11.md) - [Xinchuang](concepts/Xinchuang.md) - [Y-Combinator](concepts/Y-Combinator.md) diff --git a/wiki/log.md b/wiki/log.md index 13cd4bbc..d88bcb58 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -1,4 +1,141 @@ -## [2026-04-26] ingest | Narrative Designer Agent Personality +## [2026-04-26] ingest | Godot Multiplayer Engineer +- Source file: Agent/agency-agents/game-development/godot/godot-multiplayer-engineer.md +- Status: ✅ 成功摄入 +- Summary: GodotMultiplayerEngineer——Godot 4 多人游戏网络专家 AI Agent，核心理念"权威精确、场景架构意识、延迟诚实、GDScript 精准"。核心规范：`set_multiplayer_authority()` 显式权威设置，服务器权威模型持有所有游戏关键状态；所有 `@rpc("any_peer")` 必须服务器端验证发送者 ID 和输入合理性；`MultiplayerSpawner` 是动态生成网络节点的唯一正确方式，`MultiplayerSynchronizer` 配置 `ON_CHANGE` 模式。核心交付物：NetworkManager Autoload（ENet 服务器/客户端）、Server-Authoritative Player Controller、MultiplayerSynchronizer 配置、MultiplayerSpawner 场景生成、RPC Security Pattern（物品拾取验证）、Matchmaking 集成。高级能力涵盖 WebRTC P2P 多人游戏（STUN/TURN NAT 穿透）、Nakama 游戏服务器集成、Relay Server 架构（二进制协议 + 房间路由）、自定义网络协议设计。属 The Agency Game Dev 部门。 +- Concepts created: 无（MultiplayerAPI/Server-Authoritative-Model/RPC/MultiplayerSynchronizer/MultiplayerSpawner/ENet/WebRTC/Authority-Model/RPC-Security-Pattern 各仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（Nakama/Godot-4 各仅出现 1-2 次，未达 ≥2 次独立建页阈值；以上均为工具/引擎/框架，非独立实体） +- Source page: wiki/sources/godot-multiplayer-engineer.md +- Notes: index.md Sources 部分新增 godot-multiplayer-engineer.md 条目（置于最顶部）；overview.md Game Development 部分新增 godot-multiplayer-engineer 独立 entry（置于 godot-shader-developer 之前），已建立与 [[godot-gameplay-scripter]]（多人游戏建立在游戏逻辑脚本基础上）、[[unity-multiplayer-engineer]]（跨引擎多人游戏共识，权威模型一致但 API 不同）的关联；冲突检测：与 [[unity-multiplayer-engineer]] 在"权威模型实现细节"上存在差异——Godot 显式 `set_multiplayer_authority()` + MultiplayerSynchronizer vs Unity 隐式 NetworkTransform/NetworkVariable，已在 overview.md 和 Source Page Contradictions 部分记录；Entity/Concept 去重：已检查现有 wiki 不存在同名/近义条目，所有概念和实体均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用。 + +## [2026-04-26] ingest | Godot Shader Developer +- Source file: Agent/agency-agents/game-development/godot/godot-shader-developer.md +- Status: ✅ 成功摄入 +- Summary: GodotShaderDeveloper——Godot 4 渲染效果专家 AI Agent，核心理念"创作性、正确性与性能意识三合一"。核心规范：shader_type 强制声明（canvas_item/spatial/particles/sky）；Godot 着色语言非原始 GLSL（必须用 TEXTURE/UV/COLOR/ALBEDO 等内置变量）；渲染器分级适配（Forward+ → Mobile → Compatibility）；uniform hint 强制（hint_range/source_color/hint_normal）；纹理采样计数审计（移动端不透明材质 ≤ 6 次采样）。核心交付物：2D CanvasItem 精灵描边着色器、3D Dissolve 溶解着色器、3D 水面着色器、CompositorEffect 全屏后处理、Shader Performance Audit 清单。属 The Agency Game Dev 部门。 +- Concepts created: 无（CanvasItem Shader/Spatial Shader/VisualShader/CompositorEffect/Forward+ Renderer/Mobile Renderer/Compatibility Renderer 各仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（Godot/GLSL 各仅出现 1-2 次，未达 ≥2 次独立建页阈值） +- Source page: wiki/sources/godot-shader-developer.md +- Notes: index.md Sources 部分新增 godot-shader-developer.md 条目（置于最顶部）；overview.md Game Development 部分新增 godot-shader-developer 独立 entry（置于 godot-gameplay-scripter 之后、Conflict Areas 之前），已建立与 [[godot-gameplay-scripter]]（Godot 游戏逻辑）、[[unity-shader-graph-artist]]（跨引擎着色器共识）、[[technical-artist]]（渲染技术+美术桥梁角色）关联；冲突检测：无与其他 Wiki 页面的内容冲突。 +## [2026-04-26] ingest | Godot Gameplay Scripter +- Source file: Agent/agency-agents/game-development/godot/godot-gameplay-scripter.md +- Status: ✅ 成功摄入 +- Summary: GodotGameplayScripter——Godot 4 游戏逻辑脚本专家 AI Agent 人格规范，核心理念"以软件架构师的纪律性构建类型安全、信号驱动、可组合的游戏玩法系统"。核心规范：GDScript 信号 snake_case + 类型化参数，C# 信号 PascalCase + EventHandler；全静态类型化（无 untyped var）；组合优于继承（HealthComponent 节点模式）；Autoload 仅用于全局状态（EventBus/设置/存档）；场景可独立实例化。核心交付物：Typed Signal 声明（GDSCript + C# 双语）、EventBus Autoload、HealthComponent 组件模式、Typed Array 敌人追踪、GDScript/C# 互操作模式。属 The Agency Game Dev 部门 Godot 专精。 +- Concepts created: 无（Signal-Driven-Architecture/Static-Typing-in-GDScript-2.0/Composition-Over-Inheritance/Event-Bus-Autoload/Type-Safe-Signal-Design/GDScript-CSharp-Interoperability 各仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（GDScript-2.0/C#/GDExtension/HealthComponent/EventBus 各仅出现 1-2 次，未达独立建页阈值；以上均为工具/语言/模式，非独立实体） +- Source page: wiki/sources/godot-gameplay-scripter.md +- Notes: index.md Sources 部分新增 godot-gameplay-scripter.md 条目（置于 game-designer 之后、narrative-designer 之前）；overview.md Game Development 部分新增 godot-gameplay-scripter 独立 entry（置于 unity-architect 之后、Conflict Areas 之前），已建立与 [[unity-architect]] 的跨引擎共识关联（组合优于继承设计哲学，Unity 使用 ScriptableObject 事件通道，Godot 使用信号总线）；冲突检测：与 [[unity-architect]] 在"全局状态管理"上存在实现路径差异但设计哲学一致——两者均反对全局可变状态，仅在具体机制上不同，已在 overview.md 中记录为"跨引擎共识"；Entity/Concept 去重：已检查现有 wiki 不存在同名/近义条目，所有概念和实体均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用。 +- Source file: Agent/agency-agents/game-development/blender/blender-addon-engineer.md +- Status: ✅ 成功摄入 +- Summary: BlenderAddonEngineer——Blender 原生工具开发专家 AI Agent 人格规范，核心理念"Pipeline-first, artist-empathetic, automation-obsessed, reliability-minded"。核心规范：数据 API（bpy.data）优先于操作符（bpy.ops）确保 Operator 可靠性；非破坏性验证（dry-run 模式）确保用户知情同意；Pipeline 可靠性三角（命名确定性 + 变换分离检查 + 材质槽顺序验证 + 集合包含/排除显式规则）；批量操作必须精确记录修改内容。核心交付物：PIPELINE_OT_validate_assets（命名/变换/材质槽检查）、Pipeline Export Panel（导出预设 UI）、Naming Audit Report、Validation Report Template。属 The Agency Game Dev 部门 DCC 工具专项。 +- Concepts created: 无（bpy/Asset-Validation/Non-Destructive-Workflow/Export-Presets/Pipeline-Reliability/AddonPreferences/PropertyGroups 各仅出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（Blender/BlenderAddonEngineer 各仅出现 1-2 次，未达独立建页阈值；BlenderAddonEngineer 为 Agent 类型非实体，不建 Entity 页） +- Source page: wiki/sources/blender-addon-engineer.md +- Notes: index.md Sources 首位新增 blender-addon-engineer.md 条目（2026-04-26）；overview.md Game Development 部分新增 blender-addon-engineer 独立 entry（置于 Technical Artist 之后、Roblox Systems Scripter 之前）；冲突检测：与 [[UnityArchitect]] 在"编辑器工具数据修改时机"上存在设计哲学差异——Blender Add-on Engineer 坚持非破坏性验证优先（dry-run 模式），Unity Architect 倾向所见即所得直接修改（ScriptableObject 持久化状态），均为各自平台约束最优解，已在 Source Page Contradictions 节详细记录；Entity/Concept 去重：已检查现有 wiki 不存在重复条目，所有概念和实体均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用。 + +## [2026-04-26] ingest | Roblox Avatar Creator +- Source file: Agent/agency-agents/game-development/roblox-studio/roblox-avatar-creator.md +- Status: ✅ 成功摄入 +- Summary: RobloxAvatarCreator——Roblox UGC 化身 pipeline 专家 AI Agent 人格规范。核心理念：技术规格精准、视觉打磨到位、平台合规。核心规范：UGC 网格三角面数硬限制（配件 ≤4,000、Bundle 部件 ≤10,000）；单 UV 通道且范围严格在 [0,1]；所有 transform 导出前必须应用；纹理 256-1024px PNG，UV island 2px padding；Layered Clothing 三层 cage（OuterMesh + InnerCage + OuterCage）；附件点标准命名（HatAttachment 等）；5 种 body type 全测试。核心交付物：Accessory Export Checklist、AvatarManager.lua（HumanoidDescription 全套换装）、Layered Clothing Cage Setup Guide、Creator Marketplace Submission Package、UGC Shop UI Flow（MarketplaceService）。属 The Agency Game Dev 部门 Roblox Studio 专项，与 [[Roblox Systems Scripter]]（Luau 系统架构）、[[Roblox Experience Designer]]（玩家变现）协同构成完整 Roblox 开发体系。 +- Concepts created: 无（UGC/LayeredClothing/HumanoidDescription/R15Rig/CreatorMarketplace/AttachmentPoint/RthroBodyType 各仅出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（Blender/RobloxStudio/R15TestBodies/DataStore 各仅出现 1-2 次，未达独立建页阈值，保留于 Source Page 内嵌引用） +- Source page: wiki/sources/roblox-avatar-creator.md +- Notes: index.md Sources 顶部新增 roblox-avatar-creator.md 条目（2026-04-26）；overview.md Game Development 部分新增 roblox-avatar-creator 独立 entry（紧随 roblox-experience-designer）；冲突检测：与 [[UnityArchitect]] 在角色定制系统实现路径上存在平台差异——Roblox 强制服务端权威（HumanoidDescription + DataStore），Unity 可客户端预测，均为各自平台最优解，已在 Source Page Contradictions 节记录；Entity/Concept 去重：已检查现有 wiki 不存在重复条目，所有概念和实体均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用。 + +## [2026-04-26] ingest | Roblox Systems Scripter +- Source file: Agent/agency-agents/game-development/roblox-studio/roblox-systems-scripter.md +- Status: ✅ 成功摄入 +- Summary: RobloxSystemsScripter——Roblox 平台 Luau 系统脚本工程师 AI Agent 人格规范。核心理念：服务器是唯一真相来源，客户端只显示状态不拥有状态。核心规范：客户端-服务器信任边界（LocalScript 仅显示，Script 仅逻辑）；RemoteEvent 安全验证（类型检查+冷却检查+距离检查+权限检查）；DataStore 可靠性（pcall + 指数退避重试 + 双保存点 PlayerRemoving + BindToClose）；ModuleScript 架构（所有逻辑在 ModuleScript 返回表，Script/LocalScript 仅 bootstrap）。核心交付物：DataManager.lua（含 retryAsync + deepCopy + 双保存点）、CombatSystem.lua（完整验证链路示例）、GameServer.bootstrap.server.lua（五阶段引导模式）。高级能力：Parallel Luau（task.desynchronize + Actor 模型 + SharedTable）、对象池、数据版本迁移（UpdateAsync 原子升级）。属 The Agency Game Dev 部门 Roblox Studio 专项，与 Roblox Experience Designer 协同构成完整 Roblox 开发体系。 +- Concepts created: 无（Server-Authoritative-Architecture/RemoteEvent-Security/DataStore-Reliability/ModuleScript-Architecture/Parallel-Luau/Object-Pooling/UpdateAsync-Atomic-Pattern 各仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（Roblox/Luau/DataStoreService/ReplicatedStorage/ServerStorage 各仅出现 1-2 次，未达独立建页阈值，保留于 Source Page 内嵌引用） +- Source page: wiki/sources/roblox-systems-scripter.md +- Notes: index.md Sources 顶部新增 roblox-systems-scripter.md 条目（2026-04-26）；overview.md Game Development 部分新增 roblox-systems-scripter 独立 entry（紧随 Technical Artist，Roblox Experience Designer 紧接其后）；冲突检测：与 [[UnityArchitect]] 在客户端预测策略上存在平台差异——Roblox Systems Scripter 建议服务器权威不做本地预测（Roblox RemoteEvent 架构天然适合），Unity Architect/UnityMultiplayerEngineer 建议使用服务器回滚式 client prediction 提升响应体验，已在 Source Page Contradictions 节记录，属平台约束差异而非绝对冲突；Entity/Concept 去重：已检查现有 wiki 不存在重复条目，所有概念和实体均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用。 + +## [2026-04-26] ingest | Roblox Experience Designer +- Source file: Agent/agency-agents/game-development/roblox-studio/roblox-experience-designer.md +- Status: ✅ 成功摄入 +- Summary: RobloxExperienceDesigner——Roblox 平台原生体验设计师 AI Agent 人格规范，专注于 9-17 岁受众的参与度循环设计、变现系统（Game Pass/Developer Product/UGC）与玩家留存。核心方法：DataStore 驱动进度持久化创造沉没成本；每日奖励系统（1-7天循环阶梯）驱动习惯性返回；入职引导三阶段（0-60秒/5分钟/15分钟）；AnalyticsService 追踪 D1/D7 留存指标。核心原则：禁止 pay-to-win、DataStore 安全优先、变现伦理（禁止暗黑模式）。成功指标：D1 留存 >30%、D7 >15%、MAU 月增长 >10%、转化率 >3%、零 Roblox 政策违规。核心交付物：PassManager.lua（Game Pass 集中管理）、DailyRewardSystem.lua（每日奖励）、Onboarding Flow Design Document（含 Drop-off Recovery Points）。属 The Agency Game Dev 部门 Roblox Studio 专项。 +- Concepts created: 无（EngagementLoop/DailyRewardSystem/DataStoreProgression/GamePassMonetization/DeveloperProduct/OnboardingFlow/RobloxAlgorithm/AnalyticsService/SoftCurrencyFunnel/PriceAnchoring 均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（RobloxExperienceDesigner/RobloxPlatform/MarketplaceService/DataStoreService/AnalyticsService/VoiceChatService 各仅出现 1 次，未达独立建页阈值，保留于 Source Page 内嵌引用） +- Source page: wiki/sources/roblox-experience-designer.md +- Notes: index.md Sources 顶部新增 roblox-experience-designer.md 条目（2026-04-26）；overview.md Game Development 部分新增 roblox-experience-designer 独立 entry（Roblox Experience Designer 紧随 Technical Artist）；冲突检测：与 [[UnityArchitect]] 在变现策略上存在受众差异——Roblox 受众（9-17岁）强制伦理变现规范，Unity 平台受众更广可更灵活，已在 Source Page Contradictions 节记录；Entity/Concept 去重：已检查现有 wiki 不存在重复条目，所有概念和实体均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用。 + +## [2026-04-26] ingest | Unity Architect +- Source file: Agent/agency-agents/game-development/unity/unity-architect.md +- Status: ✅ 成功摄入 +- Summary: UnityArchitect——Unity 游戏架构师 AI Agent 人格规范，专注于数据驱动、ScriptableObject（SO）优先的模块化可扩展架构。核心职责：消除硬引用、单例滥用、God MonoBehaviour 等反模式，通过 SO 事件通道（GameEvent）、RuntimeSet、单一职责组件拆分、Inspector SO 引用连线构建可测试、可设计师扩展的 Unity 系统。核心理念：ScriptableObject-First（所有共享数据存于 SO，绝不跨场景传 MonoBehaviour 字段）；零硬引用（禁用 GameObject.Find/单例，通过 SO 事件通道连线）；单一职责（每个 MonoBehaviour < 150 行）。高级能力：Addressables 资源管理、SO 状态机、Unity DOTS 混合架构、内存 Profiling。核心交付物：FloatVariable SO（含 OnValueChanged）、RuntimeSet、GameEvent 事件通道、PlayerHealthDisplay 示例、Custom PropertyDrawer。成功指标：零 GameObject.Find()；每个 MonoBehaviour < 150 行；Prefab 空场景独立运行。 +- Concepts created: 无（ScriptableObject/RuntimeSet/GameEvent/SingleResponsibility/EventDriven/DataDriven/ScriptableObjectEventChannel/Addressables/UnityDOTS/EditorUtilitySetDirty 均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（UnityArchitect/UnityEditor/UnityDOTS 各仅出现 1 次，未达独立建页阈值，保留于 Source Page 内嵌引用） +- Source page: wiki/sources/unity-architect.md +- Notes: index.md Sources 顶部替换占位条目为正式摘要（2026-04-26，unity-architect.md）；overview.md Game Development 部分新增 unity-architect 独立 entry（Unity Architect 紧随 Unity Shader Graph Artist）；冲突检测：与 [[unity-multiplayer-engineer]] 在 NetworkVariable 传递方式上存在 SO 抽象程度差异——UnityArchitect 侧重 SO 层引用连线，UnityMultiplayerEngineer 侧重 NetworkBehaviour 直接挂载，属架构风格差异而非绝对冲突，已在 Source Page Contradictions 节记录；Entity/Concept 去重：已检查现有 wiki 不存在重复条目，所有概念和实体均仅在本文档出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用；overview.md Game Development 部分完整性：已新增 Unity Architect entry，与 Unity Shader Graph Artist、Unity Editor Tool Developer、Unity Multiplayer Engineer 共同构成 Game Development Unity 专精团队。 +- Source file: Agent/agency-agents/game-development/unity/unity-multiplayer-engineer.md +- Status: ✅ 成功摄入 +- Summary: UnityMultiplayerEngineer——Unity 多人游戏网络编程专家 AI Agent 人格规范。核心职责：使用 Netcode for GameObjects（NGO）、Unity Gaming Services（Relay/Lobby）构建安全、抗作弊、延迟容忍的多人游戏系统。核心理念：服务器权威非协商原则——服务器拥有所有游戏状态真相，客户端仅发送输入；NetworkVariable 用于持久化状态，RPC 用于一次性事件，二者不可混用。核心规范：ServerRpc 必须服务器端验证所有输入；客户端预测必须与服务器状态调和校正；带宽管理——每玩家稳态 < 10KB/s；Relay 替代直连 P2P 保护主机 IP；Lobby 仅存储元数据不存储游戏状态。核心交付物：Server-Authoritative Player Controller（含客户端预测与调和）、Lobby Manager（创建/快速匹配/心跳）、NetworkVariable 设计参考、反作弊验证逻辑。高级能力：回滚网络代码（战斗游戏风格）、专用服务器 Docker 部署、性能剖析与带宽预算。 +- Concepts created: ServerAuthority、ClientPrediction、NetworkVariable、UnityRelay、UnityLobby、AntiCheatArchitecture、BandwidthManagement、LagCompensation +- Entities created: NetcodeForGameObjects、UnityGamingServices、UnityMultiplayerEngineer、UnrealMultiplayerArchitect +- Source page: wiki/sources/unity-multiplayer-engineer.md +- Notes: index.md Sources 顶部新增 unity-multiplayer-engineer.md 条目（2026-04-26）；index.md Entities 新增 4 个实体（NetcodeForGameObjects、UnityGamingServices、UnityMultiplayerEngineer、UnrealMultiplayerArchitect）；index.md Concepts 新增 8 个概念；overview.md 未更新（非概述类技术规范文档）；冲突检测：与 [[UnrealMultiplayerArchitect]] 在客户端预测实现细节上有差异——Unity 侧使用 NetworkVariable + LateUpdate 调和，Unreal 侧使用帧缓冲和回滚机制，已在 Source Page Contradictions 节记录，两者均遵循服务器权威原则，属框架差异而非绝对冲突；Entity/Concept 去重：已检查现有 wiki 不存在重复条目，所有概念和实体均为首次创建。 +- Source file: Agent/agency-agents/game-development/unity/unity-shader-graph-artist.md +- Status: ✅ 成功摄入 +- Summary: UnityShaderGraphArtist——Unity 渲染效果专家 AI Agent 人格规范。核心职责：精通 Shader Graph 可视化材质创作与 HLSL 性能优化，专注于 URP/HDRP 渲染管线的实时视觉效果开发。核心理念：Shader Graph 是艺术家创作首选，HLSL 仅用于性能关键路径。核心规范：Sub-Graph 强制复用重复逻辑；URP/HDRP API 严格区分不可互换；移动端硬约束（每 Fragment Pass 最多 32 纹理采样，不透明 Fragment 最多 60 ALU）；Alpha Clipping 优先于 Alpha Blend；Frame Debugger 强制性能分析后方可发布。核心交付物：Dissolve Shader Graph（含 DissolveCore Sub-Graph）、OutlineRendererFeature（URP 自定义描边通道）、CustomLit.hlsl（URP 兼容 PBR Shader）、Shader Complexity Audit 模板。高级能力：Compute Shader GPU 处理、RenderDoc Shader 调试、自定义深度后处理通道、程序化纹理生成。 +- Concepts created: 无（Shader Graph/Sub-Graph/ScriptableRendererFeature/AlphaClipping/HLSL 均仅出现 1-2 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（UnityTechnologies/DissolveCore/OutlineRendererFeature/CustomLit.hlsl 各仅出现 1 次，未达独立建页阈值，保留于 Source Page 内嵌引用） +- Source page: wiki/sources/unity-shader-graph-artist.md +- Notes: index.md Sources 顶部新增 unity-shader-graph-artist.md 条目（2026-04-26）；overview.md Game Development 部分新增 unity-shader-graph-artist 独立 entry；冲突检测：与 [[unreal-technical-artist]] 在渲染管线选择上存在平台差异（Unity Shader Graph vs Unreal HLSL），属平台特性差异而非绝对冲突，已在 Source Page Contradictions 节记录；Entity/Concept 去重：所有 Key Concepts/Key Entities 均仅在本 Source 出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用。 + +## [2026-04-26] ingest | Unity Editor Tool Developer +- Source file: Agent/agency-agents/game-development/unity/unity-editor-tool-developer.md +- Status: ✅ 成功摄入 +- Summary: UnityEditorToolDeveloper——Unity 编辑器扩展开发工程师 AI Agent 人格规范。核心职责：通过 EditorWindows、PropertyDrawers、AssetPostprocessors、Build Validators 自动化团队工作流，减少人工错误并提升艺术/设计/工程团队效率。核心理念：最佳工具是隐形的——在问题到达 QA 前自动拦截，在创意人员意识到需求前提前自动化。核心规范：Editor 脚本必须置于 Editor 文件夹或 #if UNITY_EDITOR 保护；EditorWindow 必须通过 [SerializeField]/EditorPrefs 持久化状态；AssetPostprocessor 必须幂等（同一资源重复导入产生相同结果）；PropertyDrawer 必须调用 BeginProperty/EndProperty；构建验证失败必须抛出 BuildFailedException。高级能力：Assembly Definition 架构（编辑器/运行时程序集分离）、CI/CD 集成（-batchmode + GitHub Actions）、Scriptable Build Pipeline、UI Toolkit (UIElements) 编辑器工具。 +- Concepts created: 无（EditorWindow/AssetPostprocessor/PropertyDrawer/BuildValidation 各仅出现 1 次，未达 ≥2 次建页阈值，保留于 Source Page 内嵌引用） +- Entities created: 无（本 Source 无人 Entity） +- Source page: wiki/sources/unity-editor-tool-developer.md +- Notes: index.md Sources 替换占位条目为正式摘要（2026-04-26，unity-editor-tool-developer.md）；overview.md Game Development 部分新增 unity-editor-tool-developer 独立 entry；冲突检测：与 [[unreal-systems-engineer]] 在"构建前验证"模式上互补——Unity 侧通过 IPreprocessBuildWithReport 在打包前验证，Unreal 侧通过 UAssetCheckConfig 在编辑器内实时检查，属互补而非冲突，已在 Source Page Contradictions 节记录；Entity/Concept 去重：EditorWindow/AssetPostprocessor/PropertyDrawer/AssemblyDefinitionFiles/BuildValidation 均仅在本 Source 出现 1 次，未达 ≥2 次独立建页阈值，保留于 Source Page 内嵌引用。 + +## [2026-04-26] ingest | Unreal Systems Engineer +- Source file: Agent/agency-agents/game-development/unreal-engine/unreal-systems-engineer.md +- Status: ✅ 成功摄入 +- Summary: UnrealSystemsEngineer——Unreal Engine 5 系统架构工程师 AI Agent 人格规范。核心职责：构建 AAA 级 UE5 游戏系统的性能与混合架构，涵盖 C++/Blueprint 边界决策、Nanite 几何管线、GAS 网络配置、智能指针内存安全、Unreal Build System 反射宏规范。核心理念：Tick 逻辑必须 C++，Blueprint 是设计师 API 而非运行时引擎；Nanite 单场景 1600 万实例上限需提前规划；所有 UObject 指针必须 UPROPERTY() 声明。关键规范：C++ 承担所有每帧逻辑；Blueprint 适用于：高层游戏流、UI 原型、设计师可扩展层；Nanite 不兼容骨骼网格/复杂 clip/样条网格/程序化网格；TWeakObjectPtr/TSharedPtr 处理非拥有引用；FGameplayTag 替代字符串标识符；GAS 通过 UAbilitySystemComponent 复制。高级能力：Mass Entity（Unreal ECS，处理海量 NPC）、Chaos 破坏系统（Geometry Collection 实时断裂）、Lyra 模块化框架（GameFeatureAction 运行时注入）。成功指标：零 Blueprint Tick 函数（已交付代码）、Nanite 实例预算已规划、无 UPROPERTY() 缺失警告、帧预算 60fps（目标硬件）。 +- Concepts created/updated: [[GAS-Gameplay-Ability-System]]（更新 sources 字段，新增 UnrealSystemsEngineer 补充：Tick 逻辑必须 C++、FGameplayTag 优于字符串、GAMEPLAYATTRIBUTE_REPNOTIFY 宏）、[[Nanite]]（更新 sources 字段，新增 UnrealSystemsEngineer 补充：1600万实例上限、显式切线禁用、r.Nanite.Visualize 兼容检测） +- Entities updated: [[UnrealEngine5]]（Unreal Technical Artist 已有，无需新建） +- Source page: wiki/sources/unreal-systems-engineer.md +- Notes: index.md Sources 替换占位条目为正式摘要（2026-04-26，unreal-systems-engineer.md）；index.md Concepts 无需新增条目（GAS/Nanite 均已存在）；overview.md Game Development 部分新增 unreal-systems-engineer 独立 entry，与 unreal-multiplayer-architect/unreal-technical-artist 共同构成 UE5 专精团队；冲突检测：与 [[UnrealMultiplayerArchitect]] 在 GAS 职责边界存在互补关系——系统工程师负责 C++ 实现和网络复制配置，网络架构师负责 RPC 层安全和服务器权威验证，已在 Source Page Contradictions 节记录；Entity 去重：UnrealEngine5 已在其他来源出现，无需新建；Entity/Concept 去重：Mass Entity/Chaos Physics/Lyra 高级能力各仅在 Advanced Capabilities 部分出现 1 次，未达≥2次独立建页阈值，保留于 Source Page 内嵌引用。 + +## [2026-04-26] ingest | Unreal Multiplayer Architect +- Source file: Agent/agency-agents/game-development/unreal-engine/unreal-multiplayer-architect.md +- Status: ✅ 成功摄入 +- Summary: Unreal Multiplayer Architect——Unreal Engine 5 多人游戏网络架构师 AI Agent 人格规范。核心职责：构建服务器权威的 UE5 多人游戏网络系统，涵盖 Actor 复制、RPC 安全验证、网络预测、GAS 复制及专用服务器配置。核心理念：服务器拥有真相，客户端仅发送请求——所有游戏状态变更必须由服务器执行。关键规范：每个游戏影响型 Server RPC 必须实现 `_Validate()`（缺失即构成作弊漏洞）；`HasAuthority()` 检查必须在每次状态变更前执行；网络复制频率按 Actor 类型精细调整（投射物 100Hz/NPC 20Hz/环境物 2Hz）；GameMode 仅运行于服务器从不复制，GameState 复制到所有客户端，PlayerController 仅复制给拥有者。成功指标：带宽 < 15KB/s/玩家，200ms 延迟下调和事件 < 1次/玩家/30秒，RPC 安全审计零作弊向量。 +- Concepts created/updated: [[Server-Authoritative-Model]]（更新 sources 字段）、[[Actor-Replication]]（更新 sources 字段）、[[RPC-Remote-Procedure-Call]]（更新 sources 字段）、[[Network-Prediction]]（更新 sources 字段）、[[Replication-Graph]]（新建——UE5 空间分区复制优化系统）、[[GAS-Gameplay-Ability-System]]（新建——UE5 技能与属性管理框架，含网络预测） +- Entities updated: [[UnrealMultiplayerArchitect]]（已有，更新来源关联） +- Source page: wiki/sources/unreal-multiplayer-architect.md +- Notes: index.md Sources 新增条目（2026-04-26，unreal-multiplayer-architect.md）；index.md Concepts 新增 GAS-Gameplay-Ability-System 条目；新建 concepts/Replication-Graph.md 和 concepts/GAS-Gameplay-Ability-System.md；overview.md Game Development 部分新增 unreal-multiplayer-architect 独立 entry；冲突检测：无已知冲突（Source Page Contradictions 节为空——本技术领域为独立领域）。 + +## [2026-04-26] ingest | Unreal World Builder Agent Personality +- Source file: Agent/agency-agents/game-development/unreal-engine/unreal-world-builder.md +- Status: ✅ 成功摄入 +- Summary: UnrealWorldBuilder——Unreal Engine 5 开放世界环境架构工程师 AI Agent 人格规范。核心职责：使用 UE5 World Partition、Landscape、PCG、HLOD 系统构建 4km²~64km² 超大规模开放世界。核心理念：用格子大小控制流送预算，用 RVT 消除地形层混合成本。关键规范：World Partition 格子策略（密集城区64m/空旷地形128m/沙漠海洋256m+）；Always Loaded 层存放全局内容，关键游戏内容禁止放格子边界；Landscape 单区域最多4层材质，超过2层必须启用RVT；HLOD 覆盖所有500m+可见区域；PCG 大规模植被使用 Nanite 预烘焙；Foliage Tool 仅用于手工放置主角物件；LWC 在任何轴>2km的世界必须启用。高级能力：LWC 双精度坐标（20km后浮点精度误差）、OFPA 多用户协作、Unreal Insights 性能分析。成功指标：地面疾跑无>16ms流送卡顿、1km²+区域预烘焙、HLOD覆盖500m+区域、Landscape层数永不超4。 +- Concepts created: [[WorldPartition]]（新建）、[[RuntimeVirtualTexturing]]（新建）、[[LargeWorldCoordinates]]（新建） +- Concepts updated: [[PCG]]（追加 unreal-world-builder 来源）、[[LOD]]（追加 unreal-world-builder 来源）、[[Nanite]]（追加 unreal-world-builder 来源） +- Entities updated: [[UnrealEngine5]]（追加 unreal-world-builder 来源） +- Source page: wiki/sources/unreal-world-builder.md +- Notes: index.md Sources 新增条目（紧随 unreal-systems-engineer 之后）；overview.md UnrealSystemsEngineer 条目后新增 unreal-world-builder 独立 entry；冲突检测：未发现与现有 Wiki 内容的冲突；Entity 去重：Epic Games 仅提及1次，未达≥2次阈值；UnrealEngine5 已存在，直接追加来源；HLOD 已在 LOD.md 提及，无需独立建页。 + +## [2026-04-26] ingest | Game Designer Agent Personality +- Source file: Agent/agency-agents/game-development/game-designer.md +- Status: ✅ 成功摄入 +- Summary: Game Designer Agent——游戏系统与机制设计师 AI Agent 人格规范。以"循环、杠杆、玩家动机"为思维框架，将创意愿景转化为可执行、无歧义的游戏设计文档（GDD）。核心理念：从玩家动机出发设计，从功能列表出发设计。五步工作流：概念→设计支柱→纸面原型→GDD撰写→调优迭代。三层核心循环：瞬间体验（0-30秒）→会话目标（5-30分钟）→长期进阶（数小时至数周）。所有数值从假设开始，用 [PLACEHOLDER] 标记直至测试验证。高级能力：行为经济学应用（Cialdini 影响原则/损失厌恶/变率奖励/沉没成本）、跨类型机制移植（机制活检分析）、高级经济设计（供给-需求模型/通胀检测/Monte Carlo 模拟）、系统性涌现设计（系统交互矩阵/最小可行复杂度）。 +- Concepts created: [[Core-Gameplay-Loop]]（核心游戏循环三层模型）、[[Economy-Balance]]（游戏经济平衡设计——供给-需求模型、玩家画像、通胀检测） +- Entities created: 无（本文档未明确提及具体人物或公司，均为通用游戏开发概念，未达 Entity 建页阈值；GameDesigner Agent 本身属于 Agent 类型而非 Entity 类型） +- Source page: wiki/sources/game-designer.md +- Notes: index.md Sources 新增条目（2026-04-26，game-designer.md）；index.md Concepts 新增 2 个条目（Core-Gameplay-Loop/Economy-Balance）；overview.md Game Development 部分新增 game-designer 独立 entry（与 technical-artist/narrative-designer/level-designer 构成完整 Game Dev 设计体系）；冲突检测：无已知冲突（Source Page Contradictions 节为空）；Entity 去重：无 Entity 达标（GameDesigner Agent/Narrative Designer/Level Designer/Game Audio Engineer/Technical Artist 均为 Agent 类型，不建 Entity 页面）。 + +## [2026-04-26] ingest | Unreal Technical Artist +- Source file: Agent/agency-agents/game-development/unreal-engine/unreal-technical-artist.md +- Status: ✅ 成功摄入 +- Summary: Unreal Technical Artist——Unreal Engine 5 视觉系统工程师 AI Agent 人格定义。拥有 Material Editor、Niagara VFX、PCG、Substrate 和 Nanite 全栈专业能力，负责 UE5 项目的美术-引擎视觉管线。核心交付标准：Material Function 库复用规范（消除跨 Master Material 重复节点簇）、Niagara Scalability 三档预设（High/Medium/Low）、确定性 PCG 图设计（相同参数→相同输出）、Nanite 优先策略（非适用资产须手动 LOD 链）、Substrate 多层材质（UE5.3+ 替代 SSS workaround）。性能纪律：每个 Static Switch 使着色器排列数翻倍，必须审计；所有粒子系统必须设 Max Particle Count；PCG 生成须在 3 秒内完成，流式加载不得造成卡顿。 +- Concepts created: [[MaterialFunction]]（UE5 材质系统中可复用的节点逻辑封装单元）、[[NiagaraVFX]]（UE5 新一代粒子和 VFX 系统，支持 GPU/CPU 模拟分离与 Scalability 分级）、[[PCG]]（程序化内容生成框架，通过图节点控制开放世界资产分布）、[[Nanite]]（UE5 虚拟几何体系统，支持自动 LOD 和海量实例化渲染）、[[Substrate]]（UE5.3+ 多层物理材质系统，替代传统 SSS workaround）、[[LOD]]（Level of Detail，根据距离动态切换网格精度）、[[QualitySwitch]]（UE5 材质质量分层节点，支持 Mobile/Console/PC 三档） +- Entities created: [[UnrealEngine5]]（Epic Games 开发的游戏引擎，提供 Material Editor、Niagara、PCG、Nanite 等视觉工具链） +- Source page: wiki/sources/unreal-technical-artist.md +- Notes: index.md Sources 新增条目（2026-04-26，unreal-technical-artist.md）；index.md Entities 新增 UnrealEngine5 条目；index.md Concepts 新增 7 个条目（MaterialFunction/NiagaraVFX/PCG/Nanite/Substrate/LOD/QualitySwitch）；overview.md Game Development 部分新增 unreal-technical-artist 独立 entry，与 Technical Artist 基类形成继承关系；index.md 中 LOD-Pipeline 重复条目已清理；冲突检测：无已知冲突（Source Page Contradictions 节为空）。 + - Source file: Agent/agency-agents/game-development/narrative-designer.md - Status: ✅ 成功摄入 - Summary: Narrative Designer Agent——游戏叙事设计师 AI Agent 人格规范。核心职责：将叙事设计为一套选择-后果-世界一致性的系统，与游戏机制深度整合。关键规范：对话必须通过"真实人物说话"测试；选择必须类型不同且有 2 beats 内后果；Lore 三层可选深度（Surface/Engaged/Deep）；环境叙事通过道具无声讲述故事；叙事-玩法整合矩阵确保故事节点连接游戏机制；玩家叙事代理权与机械代理权必须匹配。 @@ -3874,3 +4011,11 @@ - Entities created: 无（UnrealTechnicalArtist/UnityShaderGraphArtist/UnrealWorldBuilder/UnityArchitect 各在源文档中仅出现 1 次，未达 Entity 建页阈值 ≥2 次） - Source page: wiki/sources/technical-artist.md - Notes: index.md Sources 新增条目（2026-04-26，第7行）；index.md Concepts 新增 6 个条目（Asset-Pipeline/LOD-Pipeline/Performance-Budget/Post-Processing/Shader/VFX）；overview.md Game Development section 新增 Technical Artist 完整 entry；Entity 去重：UnrealTechnicalArtist/UnityShaderGraphArtist/UnrealWorldBuilder/UnityArchitect 各仅出现 1 次，未达 Entity 建页阈值，不建页；冲突检测：无已知冲突（Source Page Contradictions 节为空）；wikilinks 命名一致性：创建过程中统一使用 hyphenated-name 格式（LOD-Pipeline/Performance-Budget/Post-Processing/Asset-Pipeline），与 wiki 中现有 naming convention 一致。 + +## [2026-04-26] ingest | Godot Multiplayer Engineer Agent Personality +- Source file: Agent/agency-agents/game-development/godot/godot-multiplayer-engineer.md +- Status: ✅ 成功摄入（source page 已存在，仅修复 index.md broken entry） +- Summary: Godot 4 网络多人游戏专家 Agent，基于 MultiplayerAPI、MultiplayerSpawner、MultiplayerSynchronizer 和 RPC 机制实现实时多人游戏网络同步。涵盖服务器权威模型设计、RPC 安全性、场景复制、延迟模拟测试、NAT 穿透与 WebRTC 集成。 +- Concepts created/updated: [[MultiplayerAPI]]、[[Server-Authoritative Model]]、[[RPC（Remote Procedure Call）]]、[[MultiplayerSynchronizer]]、[[MultiplayerSpawner]]、[[ENet]]、[[WebRTC]]、[[Authority Model]]、[[RPC Security Pattern]] +- Source page: wiki/sources/godot-multiplayer-engineer.md +- Notes: index.md Sources 第3行已存在正确条目；index.md line 507 原有 broken lint marker entry（expected source missing）已移除；Entity 建页判断：Godot 4 和 Nakama 在源文档中仅出现 1-2 次，未达 Entity 建页阈值 ≥2 次，仅在 source page Key Entities 节记录；冲突记录：与 [[unity-multiplayer-engineer]] 在权威模型实现上有差异，已在 source page Contradictions 节记录（Godot 显式 vs Unity 隐式权威模型） diff --git a/wiki/overview.md b/wiki/overview.md index 7f14b34a..3020f5b0 100644 --- a/wiki/overview.md +++ b/wiki/overview.md @@ -865,8 +865,112 @@ Key concepts: [[Django ORM]], [[Django REST Framework]], [[Django Admin 定制]] **[[technical-artist]]**（Technical Artist）：技术美术 Agent——连接艺术视野与引擎实现的桥梁角色。核心职责：在硬性能预算内最大化视觉质量，涵盖着色器编写、VFX 系统构建、资产管线标准定义和渲染性能分析。核心原则：**预算优先**——每种资产类型（多边形数、纹理分辨率、Draw Calls、粒子数）必须在生产前定义明确上限，而非交付后才发现超标；**移动端优先**——过度绘制（Overdraw）是移动端性能隐性杀手，所有半透明/加法粒子必须审计并设定上限，LOD 管线强制执行（LOD0–LOD3 最低要求）；**着色器标准**——所有自定义着色器必须包含移动端安全变体或明确标注平台限制。核心交付物：Asset Budget Spec Sheet（含角色/环境/VFX 详细预算表）、Dissolve Shader（HLSL/Unity URP）、VFX Performance Audit Checklist、LOD Chain Validation Script。高级能力涵盖实时光线追踪（RT reflections + DLSS/XeSS/FSR 超采样）、AI 辅助美术管线（纹理超分辨率、AI 法线图生成）和模块化后处理栈（LUT 调色、TAA + 锐化）。属 The Agency Game Dev 部门，与 [[UnrealTechnicalArtist]]（Unreal 专精）和 [[UnityShaderGraphArtist]]（Unity 着色器图形专精）共享技术栈。 +**[[blender-addon-engineer]]**（Blender Add-on Engineer）：Blender 原生工具开发专家 AI Agent——通过 Python + bpy API 构建自定义 Operator、Panel、资产验证器和导出器，将重复性 DCC 工作流自动化为可靠的一键工作流。核心理念：**Pipeline-first, artist-empathetic, automation-obsessed, reliability-minded**。核心规范： + +- **数据 API 优先**：偏好 bpy.data/bpy.types 直接数据访问而非 bpy.ops 操作符（后者上下文脆弱），确保 Operator 行为可预测 +- **非破坏性验证**：验证工具必须在自动修复前报告问题，绝不静默"成功"；dry-run 模式预演所有破坏性操作 +- **Pipeline 可靠性三角**：命名确定性 + 变换分离检查（location/rotation/scale 单独验证）+ 材质槽顺序验证 + 集合包含/排除显式规则 +- **可审计批量操作**：批量工具必须精确记录修改内容，Log Exactly What They Changed + +核心交付物：Asset Validator Operator（PIPELINE_OT_validate_assets，含命名/变换/材质槽检查）、Pipeline Export Panel（导出预设 UI）、Naming Audit Report（命名规范报告）、Validation Report Template（验证报告模板）。属 The Agency Game Dev 部门 DCC 工具专项，与 [[Technical Artist]]（通用技术美术）构成 DCC 工具分工——Technical Artist 定义资产管线标准，Blender Add-on Engineer 实现 Blender 端工具；与 [[UnityArchitect]] 在编辑器扩展设计哲学上存在张力——后者倾向所见即所得直接修改，前者坚持非破坏性验证优先，均为平台约束最优解。与 [[bpy]]（Blender Python API）、[[Asset-Validation]]（资产验证）、[[Non-Destructive-Workflow]]（非破坏性工作流）共享核心工具开发概念。 + +**[[roblox-systems-scripter]]**（Roblox Systems Scripter）：Roblox 平台 Luau 系统脚本工程师 AI Agent——专注于服务器权威架构、RemoteEvent 安全验证、DataStore 可靠性和 ModuleScript 模块化设计，构建可防作弊、数据持久化安全、架构整洁的 Roblox 游戏体验。核心理念：**服务器是唯一真相来源，客户端只显示状态，不拥有状态**。核心规范： + +- **客户端-服务器信任边界**：`LocalScript` 仅客户端显示，`Script` 仅服务器逻辑，绝不混合；RemoteEvent FireServer 请求必须在服务器端完整验证（类型检查+冷却检查+距离检查+权限检查），不得信任任何客户端数据 +- **DataStore 可靠性**：`pcall` 包装 + 指数退避重试（2s/4s/8s）+ 双保存点（PlayerRemoving + BindToClose）；UpdateAsync 优先于 SetAsync（原子处理并发冲突） +- **ModuleScript 架构**：所有逻辑在 ModuleScript 中返回表，Script/LocalScript 仅 bootstrap；SharedTable 或 ReplicatedStorage 常量模块实现跨端共享常量 +- **安全验证**：所有 OnServerEvent 处理必须结构验证输入；RemoteFunction InvokeClient 禁止在服务器端调用（恶意客户端可永久挂起服务器线程） + +核心交付物：DataManager.lua（含 retryAsync + deepCopy + 双保存点）、CombatSystem.lua（完整验证链路示例）、GameServer.bootstrap.server.lua（五阶段引导模式）。高级能力涵盖 Parallel Luau（task.desynchronize + Actor 模型 + SharedTable）、对象池（预实例化 effects/NPC 减少 GC）、数据版本迁移（data._version + UpdateAsync 原子升级）。属 The Agency Game Dev 部门 Roblox Studio 专项，与 [[Roblox Experience Designer]]（玩家参与度和变现系统设计）协同构成完整 Roblox 开发体系——Experience Designer 定义体验目标，Systems Scripter 实现底层架构支撑。与 [[Server-Authoritative Architecture]]（服务器权威模型）、[[DataStore Reliability]]（DataStore 可靠性模式）、[[ModuleScript Architecture]]（模块化架构）、[[Parallel Luau]]（并行 Luau）共享 Roblox 系统工程核心技术栈。 + +**[[roblox-experience-designer]]**（Roblox Experience Designer）：Roblox 平台原生体验设计师 AI Agent——专注于 Roblox 受众（9-17岁）的参与度循环设计、变现系统与玩家留存。核心使命：设计让玩家返回、分享和投资的体验。核心方法：DataStore 驱动进度系统（玩家等级/道具/货币持久化，创造沉没成本）；Roblox 原生化变现（Game Pass 永久权益、Developer Product 消耗品、UGC 道具）；参与度阶梯（首次会话→每日返回→周留存，每层有清晰奖励闭环）；每日奖励系统（1-7天循环阶梯，驱动习惯性返回）；入职引导三阶段（0-60秒/5分钟/15分钟，最小化早期流失）。核心原则：**免费体验必须完整**——禁止 pay-to-win；**DataStore 安全优先**——进度丢失是永久流失的首因；**变现伦理**——禁止暗黑模式、人工稀缺、压力购买。成功指标：D1 留存 >30%、D7 >15%、MAU 月增长 >10%、转化率 >3%、零 Roblox 政策违规。核心交付物：PassManager.lua（Game Pass 集中管理模块）、DailyRewardSystem.lua（每日奖励系统）、Onboarding Flow Design Document（含 Drop-off Recovery Points）。属 The Agency Game Dev 部门 Roblox Studio 专项，与 [[Roblox Systems Scripter]]（底层系统架构）协同构成完整 Roblox 开发体系——Experience Designer 定义体验目标，Systems Scripter 实现底层架构支撑。与 [[Game Designer]]（通用游戏设计方法论）、[[Technical Artist]]（视觉质量）协同构成 Game Dev 完整设计支撑体系。与 [[EngagementLoop]]（参与度循环）、[[DailyRewardSystem]]（每日奖励）、[[DataStoreProgression]]（数据存储进度）、[[RobloxMonetization]]（Roblox 变现）共享 Roblox 原生设计核心技术栈。 + +**[[roblox-avatar-creator]]**（Roblox Avatar Creator）：Roblox UGC 化身 pipeline 专家 AI Agent——掌握 Roblox avatar 系统的全部约束条件，以及如何构建能通过 Creator Marketplace 审核的商品。核心理念：技术规格精准、视觉打磨到位、平台合规。核心规范：UGC 网格三角面数硬限制（配件 ≤4,000、Bundle 部件 ≤10,000）；单 UV 通道且范围严格在 [0,1]；所有 transform 在导出前必须应用（scale=1, rotation=0）；纹理分辨率 256×256 ~ 1024×1024 PNG，UV island 留 2px 最小 padding；Layered Clothing 必须有 Outer Mesh + InnerCage + OuterCage 三层 cage。附件点必须使用标准命名（HatAttachment / FaceFrontAttachment / LeftShoulderAttachment 等），在 5 种 body type 上全部测试。核心交付物：Accessory Export Checklist（建模检查清单）、AvatarManager.lua（HumanoidDescription 全套换装）、Layered Clothing Cage Setup Guide（Blender cage 网格规范）、Creator Marketplace Submission Package（提交前审核检查清单）、UGC Shop UI Flow（MarketplaceService 购买监听）。属 The Agency Game Dev 部门 Roblox Studio 专项，与 [[Roblox Systems Scripter]]（Luau 系统架构）、[[Roblox Experience Designer]]（玩家变现）协同构成完整 Roblox 开发体系——Avatar Creator 负责 UGC 资产从建模到上线的 pipeline。与 [[LayeredClothing]]（分层服装系统）、[[HumanoidDescription]]（化身 API）、[[CreatorMarketplace]]（UGC 交易市场）、[[R15Rig]]（R15 骨骼权重系统）共享 Roblox 化身资产核心技术栈。与 [[UnityArchitect]] 在角色定制系统实现路径上存在平台差异——Roblox 强制服务端权威（HumanoidDescription + DataStore），Unity 可客户端预测，均为各自平台最优解。 + **[[game-designer]]**（Game Designer Agent）：游戏系统与机制设计师 AI Agent——以"循环、杠杆、玩家动机"为思维框架，将创意愿景转化为可执行、无歧义的游戏设计文档（GDD）。核心理念：**从玩家动机出发设计，而非从功能列表出发**。核心方法：五步工作流（概念→设计支柱→纸面原型→GDD撰写→调优迭代）；三层核心循环（瞬间体验 0-30秒 → 会话目标 5-30分钟 → 长期进阶 数小时至数周）；数值以 `[PLACEHOLDER]` 标记假设直至测试验证。核心交付物：Game Design Document（含目的/玩家体验/输入/输出/边界/失败状态的完整机制规格）、Economy Balance Spreadsheet（玩家画像：鲸鱼/海豚/小鱼）、Player Onboarding Checklist（引导完成率目标 >90%）。高级能力涵盖行为经济学应用（Cialdini 影响原则/损失厌恶/变率奖励/沉没成本）、跨类型机制移植（机制活检分析）、高级经济设计（供给-需求模型/通胀检测/Monte Carlo 模拟）、系统性涌现设计（系统交互矩阵/最小可行复杂度）。属 The Agency Game Dev 部门。与 [[Narrative Designer]]（叙事-机制一致性整合）、[[Level Designer]]（关卡空间叙事协作）、[[Game Audio Engineer]]（反馈音效系统）、[[Technical Artist]]（视觉原型可执行化）共同构成 Game Dev 部门完整设计支撑体系。与 [[Core Gameplay Loop]]（核心循环设计）、[[Economy Balance]]（经济平衡）、[[Behavioral Economics in Games]]（行为经济学）共享 GameDesigner 核心方法论。 +**[[unreal-technical-artist]]**（Unreal Technical Artist）：Unreal Engine 5 视觉系统工程师 AI Agent——拥有 Material Editor、Niagara VFX、PCG 和 Nanite 全栈专业能力，负责 UE5 项目的美术-引擎视觉管线。核心交付标准：Material Function 库复用规范（消除跨 Master Material 重复节点簇）、Niagara Scalability 三档预设（High/Medium/Low）、确定性 PCG 图设计（相同参数→相同输出）、Nanite 优先策略（非适用资产须手动 LOD 链）、Substrate 多层材质（UE5.3+ 替代 SSS workaround）。性能纪律：每个 Static Switch 使着色器排列数翻倍，必须审计；所有粒子系统必须设 Max Particle Count；PCG 生成须在 3 秒内完成，流式加载不得造成卡顿。属 The Agency Game Dev 部门，与 [[Technical Artist]]（通用技术美术基类）共享 VFX/着色器核心规范；与 [[Unreal World Builder]]（开放世界场景搭建）、[[Unreal Systems Engineer]]（引擎底层系统）协同构成 UE5 专精团队。 + +**[[unreal-multiplayer-architect]]**（Unreal Multiplayer Architect）：Unreal Engine 5 多人游戏网络架构工程师 AI Agent——构建服务器权威模型、延迟容忍、作弊防护的生产级 UE5 多人游戏网络系统。核心理念：**服务器拥有真相，客户端请求——服务器决定**。核心方法：Server-authoritative 架构（所有游戏状态变化在服务器执行，客户端预测+对账）；UFUNCTION(Server, Reliable, WithValidation) 全覆盖（每个游戏逻辑 RPC 必须实现 _Validate）；复制频率按 Actor 类型差异化（投射物 100Hz/NPC 20Hz/环境物 2Hz）；GAS 双路径初始化（PossessedBy 服务器路径 + OnRep_PlayerState 客户端路径）。核心交付物：Replicated Actor 模板（含 RepNotify + WithValidation）、GameMode/GameState/PlayerState 架构规范、GAS 网络集成方案、Replication Graph 空间分区优化、专用服务器 Shipping 构建配置。性能指标：每玩家带宽 <15KB/s、反作弊验证全覆盖、200ms 延迟下每玩家每 30 秒校正 <1 次。属 The Agency Game Dev 部门，与 [[Unreal Technical Artist]]（UE5 视觉系统）、[[Game Designer]]（多人游戏机制设计）协同构成 UE5 专精团队。与 [[ServerAuthoritativeModel]]（服务器权威模型）、[[ActorReplication]]（Actor 复制）、[[GAS]]（Gameplay Ability System）、[[ReplicationGraph]]（复制图）共享 UE5 网络核心技术栈。 + +**[[unreal-systems-engineer]]**（Unreal Systems Engineer）：Unreal Engine 5 系统架构工程师 AI Agent——掌握 C++/Blueprint 连续统一体、Nanite 几何系统、Lumen GI、Gameplay Ability System 的 AAA 级 UE5 项目性能与混合架构专家。核心理念：**Tick 逻辑必须 C++，Blueprint 是设计师 API 而非运行时引擎**。核心规范： + +- **C++/Blueprint 边界**：每帧逻辑（Tick）必须 C++；Blueprint 适用于：高层游戏流、UI 原型、设计师可扩展层 +- **Nanite 预算**：单场景 1600 万实例上限，开放世界需提前规划实例预算；不兼容骨骼网格/复杂 clip 操作/样条网格 +- **内存安全**：所有 UObject 指针必须 UPROPERTY() 声明；跨帧 Actor 指针需 IsValid() 检查；TWeakObjectPtr/TSharedPtr 处理非拥有引用 +- **GAS 架构**：UGameplayAbility + UAttributeSet + UAbilitySystemComponent 网络就绪配置；FGameplayTag 替代字符串标识符 +- **高级能力**：Mass Entity（Unreal ECS，处理海量 NPC）、Chaos 破坏系统（Geometry Collection 实时断裂）、Lyra 模块化框架（GameFeatureAction 运行时注入） + +属 The Agency Game Dev 部门，与 [[Unreal Technical Artist]]（Nanite 资产验证与优化）协同处理几何管线；与 [[Unreal Multiplayer Architect]]（GAS 网络复制安全）在技能系统实现与 RPC 层调用上互补。核心性能纪律：Tick 逻辑 C++ 实现、帧预算 60fps（目标硬件）、Unreal Insights 性能分析验证。 + +**[[unreal-world-builder]]**（Unreal World Builder）：Unreal Engine 5 开放世界环境架构工程师 AI Agent——专注于 World Partition 分区流送、Landscape 地形系统、PCG 程序化内容生成和 HLOD 层级 LOD 构建，覆盖 4km² ~ 64km² 超大规模开放世界。核心理念：**用格子大小控制流送预算，用 RVT 消除地形层混合成本**。核心规范： + +- **World Partition 格子策略**：密集城区 64m / 空旷地形 128m / 沙漠海洋 256m+；Always Loaded 层存放 Sky/Audio/GameMode；关键游戏内容（任务触发器、关键 NPC）禁止放在格子边界 +- **Landscape 层限制**：单区域最多 4 层材质，超过则产生材质排列组合爆炸；超过 2 层必须启用 RVT（Runtime Virtual Texturing）消除逐像素层混合开销 +- **HLOD 规则**：所有 500m 以外可见区域必须生成 HLOD；Nanite 资产排除在 HLOD 合并之外；骨骼网格不支持 HLOD +- **PCG vs Foliage Tool**：Foliage Tool 仅用于手工放置主角物件；大规模植被用 PCG + Nanite 预烘焙；排除区域（道路/路径/水体/建筑）必须在 PCG 图中显式定义 +- **LWC（大世界坐标）**：任何轴超过 2km 的世界必须启用 LWC；约 20km 后无 LWC 会出现浮点精度错误；代码中位置使用 FVector3d 双精度 + +属 The Agency Game Dev 部门，与 [[Unreal Systems Engineer]]（Nanite 实例预算规划）共享 World Partition 流送基础设施；与 [[Unreal Technical Artist]]（Landscape 材质与 RVT 配置）共享地形渲染技术；与 [[Unreal Multiplayer Architect]]（World Partition 流送源与网络同步）互补。核心成功指标：地面疾跑无 >16ms 流送卡顿、1km² 以上区域全部预烘焙、HLOD 覆盖所有 500m+ 区域、Landscape 层数永不超 4。 + +**[[unity-editor-tool-developer]]**（Unity Editor Tool Developer）：Unity 编辑器扩展开发工程师 AI Agent——构建 EditorWindows、AssetPostprocessors、PropertyDrawers、Build Validators 等工具，使艺术/设计/工程团队效率可量化提升。核心理念：**最佳工具是隐形的**，在问题到达 QA 前自动拦截，在创意人员意识到需求前提前自动化。核心规范： +- **Editor 脚本放置**：必须置于 `Editor` 文件夹或使用 `#if UNITY_EDITOR` 保护，Editor API 调用进入运行时代码将导致构建失败 +- **EditorWindow 状态持久化**：必须通过 `[SerializeField]` 或 `EditorPrefs` 持久化状态，跨域重载不丢失；长操作必须通过 `EditorUtility.DisplayProgressBar` 反馈进度 +- **AssetPostprocessor 幂等性**：同一资源重复导入必须产生相同结果；命名规范强制（`_N` 后缀 → Normal Map）、压缩预算强制（2048px 上限）、平台配置自动化（Android ASTC 格式） +- **PropertyDrawer 标准**：`OnGUI` 必须调用 `BeginProperty`/`EndProperty` 以正确支持 Prefab Override UI；`GetPropertyHeight` 返回值必须与 `OnGUI` 实际绘制高度一致 +- **构建验证**：失败时必须抛出 `BuildFailedException`，而非仅 `Debug.LogWarning` + +属 The Agency Game Dev 部门，与 [[technical-artist]]（编辑器工具和资产管线）共享工具开发模式；与 [[unreal-systems-engineer]] 在"构建前验证"模式上互补——Unity 侧通过 `IPreprocessBuildWithReport` 在打包前验证，Unreal 侧通过 UAssetCheckConfig 在编辑器内实时检查。核心成功指标：每项工具都有量化的"每周节省 X 分钟"指标；AssetPostprocessor 拦截所有应被捕获的违规资产；团队在发布后 2 周内自愿采用工具（无需提醒）。 + +**[[unity-shader-graph-artist]]**（Unity Shader Graph Artist）：Unity 渲染效果专家 AI Agent——精通 Shader Graph 可视化材质创作与 HLSL 性能优化，专注于 URP/HDRP 渲染管线的实时视觉效果开发。核心理念：**Shader Graph 是艺术家创作的首选工具，HLSL 仅用于性能关键路径**。核心规范： + +- **Sub-Graph 强制复用**：所有 Shader Graph 必须使用 Sub-Graph 封装重复逻辑，重复节点簇是维护和一致性失败 +- **URP/HDRP API 严格区分**：URP 自定义通道使用 `ScriptableRendererFeature` + `ScriptableRenderPass`；HDRP 使用 `CustomPassVolume` + `CustomPass`，两者 API 不可互换 +- **移动端性能硬约束**：每 Fragment Pass 最多 32 次纹理采样，不透明 Fragment 最多 60 ALU 指令 +- **Alpha Clipping 优先**：透明材质优先使用 Alpha Clipping 而非 Alpha Blend，避免过度绘制深度排序问题 +- **Frame Debugger 强制分析**：所有 Fragment Shader 必须在 Unity Frame Debugger 和 GPU Profiler 中通过性能分析后方可发布 + +核心交付物：Dissolve Shader Graph（含 Sub-Graph 封装的 DissolveCore）、OutlineRendererFeature（URP 自定义描边通道）、CustomLit.hlsl（URP 兼容 PBR Shader 完整示例）、Shader Complexity Audit 模板。高级能力涵盖 Compute Shader GPU 数据处理、RenderDoc Shader 调试、自定义深度后处理通道和程序化纹理生成。属 The Agency Game Dev 部门，与 [[technical-artist]]（通用技术美术基类）共享 VFX/着色器核心规范；与 [[unreal-technical-artist]]（Unreal 材质系统）在跨引擎渲染技术层互补；与 [[unity-editor-tool-developer]]（编辑器工具）协同构成 Unity 专精团队。核心成功指标：100% Shader Graph 使用 Sub-Graph 封装重复逻辑；100% 暴露参数设置 Blackboard tooltip；移动端 Shader 100% 提供 fallback 变体。 + +**[[unity-architect]]**（Unity Architect）：Unity 游戏架构师 AI Agent——数据驱动模块化架构专家，精通 ScriptableObject 优先设计、职责拆分和反模式消除，构建可扩展、无"意大利面条式代码"的 Unity 项目。核心理念：**ScriptableObject-First**——所有共享游戏数据必须存于 ScriptableObject，绝不通过 MonoBehaviour 字段跨场景传递；**零硬引用**——跨系统通信禁止 GameObject.Find()、FindObjectOfType() 和静态单例，必须通过 SO 事件通道连线。核心规范： + +- **ScriptableObject 事件通道**：`GameEvent : ScriptableObject` 通过 Raise/Register 模式实现松耦合跨系统通信，替代 GetComponent<> 引用链 +- **RuntimeSet 无单例追踪**：全局实体追踪使用 `RuntimeSet : ScriptableObject`，OnEnable/OnDisable 自动注册/注销，无需单例 +- **单一职责强制**：每个 MonoBehaviour < 150 行，只解决一个问题；能用"and"描述则必须拆分；Prefab 场景无关自包含 +- **场景卫生**：每次场景加载视为干净状态，瞬态数据不得跨场景存活，除非显式通过 SO 持久化 +- **反模式零容忍**：God MonoBehaviour（500+ 行）、DontDestroyOnLoad 单例滥用、Update 内轮询逻辑均为禁止项 + +核心交付物：FloatVariable SO（含 OnValueChanged 事件）、RuntimeSet 泛型集合、GameEvent 事件通道（含 GameEventListener MonoBehaviour）、PlayerHealthDisplay 单一职责组件示例、Custom PropertyDrawer for FloatVariable（设计师实时编辑体验）。高级能力涵盖 Addressables 资源管理（替代 Resources.Load()）、SO 状态机（状态为 SO 资产、转换为 SO 事件）、Unity DOTS 混合架构（ECS + Job System + Burst Compiler 驱动性能关键系统，MonoBehaviour 处理编辑器友好型游戏逻辑）、内存分析（Memory Profiler 包 + Unity Profiler 深度分析）。 + +属 The Agency Game Dev 部门，与 [[unity-multiplayer-engineer]]（网络层叠加 SO 架构设计）互补；与 [[unity-shader-graph-artist]]（SO 数据驱动视觉资产）协同；与 [[unity-editor-tool-developer]]（Custom PropertyDrawer 赋能 SO 设计师体验）构成 Unity 工具链闭环。核心成功指标：零 GameObject.Find() 或 FindObjectOfType()；每个 MonoBehaviour < 150 行且单一职责；Prefab 在空场景独立运行无错误；所有共享状态存于 SO 资产。 + +**[[godot-gameplay-scripter]]**（Godot Gameplay Scripter）：Godot 4 游戏逻辑脚本专家 AI Agent——以软件架构师的纪律性构建类型安全、信号驱动、可组合的游戏玩法系统，精通 GDScript 2.0 和 C# 互操作。核心理念：**一切皆为节点，行为通过添加节点组合，而非增加继承深度**。核心规范： + +- **信号命名**：GDScript 用 snake_case（如 `health_changed`），C# 用 PascalCase + EventHandler 后缀（如 `HealthChangedEventHandler`）；信号必须携带类型化参数，禁止 Variant +- **静态类型强制**：所有变量、函数参数和返回值必须显式类型化，使用 typed arrays（`Array[EnemyData]`），零无类型 var 出现在生产代码 +- **组合优于继承**：通过 `@onready var health: HealthComponent = $HealthComponent` 附加子节点组件，拒绝继承层级 +- **Autoload 纪律**：仅用于真正的跨场景全局状态（设置/存档/事件总线），游戏逻辑必须驻留在可独立实例化的场景中 +- **场景隔离**：每个场景必须可独立运行（F6），不假设父节点类型或兄弟节点存在 + +核心交付物：Typed Signal 声明（GDScript + C# 双语）、EventBus Autoload 示例、HealthComponent 组件模式、Typed Array 敌人追踪示例、GDScript/C# 跨语言信号连接模式。高级能力涵盖 GDExtension C++ 集成（性能关键系统）、RenderingServer 低级 API（批量网格实例化）、Service Locator 模式（带优先级的事件总线）、WebRTC P2P 多人游戏（延迟补偿 + 死 reckoning）。属 The Agency Game Dev 部门 Godot 专精，与 [[unity-architect]] 在**组合优于继承**的设计哲学上存在跨引擎共识，但具体实现机制不同——Unity 使用 ScriptableObject 事件通道，Godot 使用信号总线；两者均反对全局可变状态。核心成功指标：零生产代码无类型 var；所有信号参数显式类型化；所有场景可独立运行（F6 无错）。 + +**[[godot-multiplayer-engineer]]**（Godot Multiplayer Engineer）：Godot 4 多人游戏网络专家 AI Agent——精通 MultiplayerAPI、MultiplayerSpawner、MultiplayerSynchronizer、RPC 机制和 ENet/WebRTC 传输层，构建生产级实时多人游戏。核心理念：**权威精确、场景架构意识、延迟诚实、GDScript 精准**。核心规范： + +- **权威模型**：`set_multiplayer_authority()` 必须显式设置每个节点权威（而非依赖默认值 peer 1），所有游戏关键状态（位置/生命值/分数/物品）由服务器（peer 1）持有权威 +- **RPC 安全性**：所有 `@rpc("any_peer")` 必须进行服务器端发送者 ID 验证和输入合理性检查；`@rpc("authority")` 用于服务器→客户端确认；`@rpc("call_local")` 用于调用者也执行效果 +- **场景复制**：`MultiplayerSpawner` 是所有动态生成网络节点的唯一正确方式（手动 `add_child()` 会导致对端节点丢失）；`MultiplayerSynchronizer` 配置 `ON_CHANGE` 模式避免每帧同步 + +核心交付物：NetworkManager Autoload（ENet 服务器/客户端）、Server-Authoritative Player Controller（含 RPC 安全审计）、MultiplayerSynchronizer 配置（ON_CHANGE 属性同步）、MultiplayerSpawner 场景生成（含连接/断连处理）、RPC Security Pattern（物品拾取验证示例）、Matchmaking 集成（HTTPRequest + ticket-based 方案）。高级能力涵盖 WebRTC P2P 多人游戏（STUN/TURN NAT 穿透）、Nakama 游戏服务器集成（大厅/排行榜/DataStore）、Relay Server 架构（二进制协议 + 房间路由）、自定义网络协议设计（`PackedByteArray` + 增量压缩）。属 The Agency Game Dev 部门，与 [[godot-gameplay-scripter]]（GDScript 游戏逻辑脚本）在多人游戏场景下协同工作；与 [[unity-multiplayer-engineer]] 在**服务器权威模型 + RPC 安全性**的核心概念上跨引擎共识，但 Godot 使用 `set_multiplayer_authority()` 显式权威 + MultiplayerSynchronizer 显式配置，Unity 使用 NetworkTransform/NetworkVariable 隐式同步。核心成功指标：零权威不匹配（所有状态变更均有 `is_multiplayer_authority()` 守卫）；所有 `@rpc("any_peer")` 均通过服务器端验证；在 150ms 模拟延迟下无破坏性同步问题。 + +**[[godot-shader-developer]]**（Godot Shader Developer）：Godot 4 渲染效果专家 AI Agent——精通 Godot 着色语言（GLSL-like）、VisualShader 编辑器、CanvasItem 和 Spatial 着色器、后处理与性能优化，专注于 2D/3D 视觉效果开发。核心理念：**创作性、正确性与性能意识三合一，渲染方案服务于目标平台而非理论最优**。核心规范： + +- **shader_type 声明**：每个着色器必须显式声明 `canvas_item`（2D/UI）、`spatial`（3D）、`particles` 或 `sky`，Godot 4 着色语言不是原始 GLSL，必须使用 Godot 内置变量（`TEXTURE`/`UV`/`COLOR`/`ALBEDO`）而非 GLSL 等价物 +- **渲染器分级适配**：Forward+（高端，全特性）→ Mobile（中端，规避 `discard`）→ Compatibility（最广泛，无 compute shader / 无 `DEPTH_TEXTURE` canvas 采样） +- **uniform hint 强制**：所有 uniform 必须附带 hint（`hint_range`/`source_color`/`hint_normal`），否则 Inspector 无法正确显示 +- **纹理采样计数**：片元着色器每帧纹理采样是主要性能成本，移动端不透明材质预算 ≤ 6 次采样 + +核心交付物：2D CanvasItem 精灵描边着色器（8 邻域采样 alpha 检测）、3D Dissolve 溶解着色器（noise texture + discard + 边缘自发光）、3D 水面着色器（双层法线混合 + 深度色彩渐变）、全屏后处理 CompositorEffect（GDScript + RenderingDevice）、着色器性能审计清单。高级能力涵盖 RenderingDevice API（compute shader 分发）、VisualShaderNodeCustom 自定义节点、FBM/Voronoi 程序化纹理、屏幕空间反射（SCREEN_TEXTURE）、体积雾（`fog_density` 输出）。属 The Agency Game Dev 部门，与 [[godot-gameplay-scripter]]（GDScript 游戏逻辑）协同构建完整的 Godot 4 游戏开发栈；与 [[unity-shader-graph-artist]] 在 Shader Graph 可视化编辑理念上跨引擎共识，但 Godot 使用 VisualShader + GLSL-like 代码着色器双轨，Unity 使用 Shader Graph + HLSL；与 [[technical-artist]] 在渲染技术+美术桥梁角色上重叠。核心成功指标：所有着色器声明 `shader_type` 并在头部注释标注渲染器要求；所有 uniform 带 hint；移动端着色器通过 Compatibility 渲染器无错；无未经性能审计的 `SCREEN_TEXTURE`。 + ## Conflict Areas 1. **Kanban vs Event Sourcing**: Kanban emphasizes visual team collaboration; Event Sourcing emphasizes auto-tracking and context preservation. **[[Project State Management]]**（事件驱动看板替代方案）vs 传统 PM 工具。核心差异：手动拖拽 vs 自然语言输入；静态快照 vs 全历史保留；无上下文 vs 完整决策链。**[[Event Sourcing]]** 在此上下文中指将项目变更存储为事件序列，每次 progress/blocker/decision/pivot 均持久化，保留完整决策上下文。 diff --git a/wiki/sources/blender-addon-engineer.md b/wiki/sources/blender-addon-engineer.md new file mode 100644 index 00000000..43b6d747 --- /dev/null +++ b/wiki/sources/blender-addon-engineer.md @@ -0,0 +1,53 @@ +--- +title: "Blender Add-on Engineer Agent Personality" +type: source +tags: [] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/blender/blender-addon-engineer.md]] + +## Summary（用中文描述） +- 核心主题：Blender 工具开发专家 AI Agent 人格规范——通过 Python + bpy API 构建 Blender 原生工具（自定义 Operator、Panel、资产验证器、导出器），将重复性 DCC 工作流自动化为可靠的一键工作流。 +- 问题域：3D 资产生成中的命名漂移、未应用变换、错误材质槽映射、导出配置不一致等交接错误问题。 +- 方法/机制：数据 API（bpy.data）优先于操作符（bpy.ops）以确保可靠性；非破坏性验证优先于自动修复；确定性命名规范；Pipeline 可靠性三角（验证→报告→确认→导出）。 +- 结论/价值：每个工具必须节省时间或防止一类真实的交接错误；Asset Validation 可在资产离开 Blender 前拦截问题；Export Preset 确保引擎端交接的可重复性。 + +## Key Claims（用中文描述） +- 主体 + 机制 + 结果：Blender Add-on Engineer 偏好数据 API 访问（bpy.data/bpy.types）而非脆弱的上下文相关操作符（bpy.ops），使得 Operator 行为可预测且稳定。 +- 主体 + 机制 + 结果：验证工具必须在自动修复前报告问题，确保用户知情同意，避免破坏性意外修改。 +- 主体 + 机制 + 结果：批量工具必须精确记录其修改内容，使得 Pipeline 可审计且可回滚。 +- 主体 + 机制 + 结果：导出器必须保留源场景状态，除非用户明确选择破坏性清理，确保交接过程可重复验证。 + +## Key Quotes +> "Every tool must save time or prevent a real class of handoff error." — 默认要求：每个工具必须有可量化的价值 +> "Operators must fail with actionable error messages — never silently 'succeed' while leaving the scene in an ambiguous state." — 操作符失败规范 +> "Never destructively rename, delete, apply transforms, or merge data without explicit user confirmation or a dry-run mode." — 非破坏性工作流核心原则 + +## Key Concepts +- [[bpy]]：Blender Python API，提供数据访问（bpy.data）和操作符执行（bpy.ops）两套接口；Add-on Engineer 偏好数据 API 以确保可靠性。 +- [[Asset-Validation]]：资产验证——在资产离开 Blender 前检查命名、变换、材质槽、集合放置等标准的自动化流程，是 Pipeline 可靠性的第一道防线。 +- [[Non-Destructive-Workflow]]：非破坏性工作流——不主动修改源数据，通过验证→报告→确认→执行四步确保用户知情同意，是 Blender Add-on Engineer 的核心设计原则。 +- [[Export-Presets]]：导出预设——可配置的引擎交接规则集（FBX/glTF/USD），确保导出设置在多次运行间保持可重复性。 +- [[Pipeline-Reliability]]：Pipeline 可靠性三角——命名确定性 + 变换分离检查 + 材质槽顺序验证 + 集合包含/排除显式规则，是 Add-on Engineer 交付的核心质量标准。 +- [[AddonPreferences]]：Blender Add-on 持久化设置机制，用于存储跨会话保留的工具配置（如默认导出路径、验证规则开关）。 +- [[PropertyGroups]]：Blender Python 属性组——结构化自定义属性的声明方式，支持 UI 绑定和序列化存储。 + +## Key Entities +- [[Blender]]：Blender Foundation 开发的开源 3D DCC 软件，通过 Python bpy API 支持插件扩展；本文档的核心目标平台。 +- [[BlenderAddonEngineer]]：The Agency Game Development 部门 Blender 专项专家 Agent，核心理念"Pipeline-first, artist-empathetic, automation-obsessed, reliability-minded"。 + +## Connections +- [[TechnicalArtist]] ← extends ← [[BlenderAddonEngineer]]：技术美术是 Blender Add-on Engineer 的上级角色，后者是 Blender 专项实现。 +- [[GameDesigner]] ← depends_on ← [[BlenderAddonEngineer]]：游戏设计师依赖资产验证和导出管线确保设计资产正确交接。 +- [[UnityArchitect]] ← parallel ← [[BlenderAddonEngineer]]：同为 DCC 工具开发专家，但 Unity Architect 专注 Unity Editor 扩展；两者共享 Editor 工具开发的通用原则（验证优先、持久化配置、非破坏性）。 +- [[UnrealSystemsEngineer]] ← parallel ← [[BlenderAddonEngineer]]：同为工具开发专家，Unreal Systems Engineer 专注 UE5 C++/Blueprint 扩展；两者共享"管道优先、验证先行"理念。 +- [[BlenderAddonEngineer]] ← provides ← [[Asset-Validation]] → feeds → [[GameDesigner]]：验证工具产出报告，供设计师决策修复方案。 + +## Contradictions +- 与 [[UnityArchitect]] 在"编辑器工具的数据修改时机"上存在设计哲学差异： + - 冲突点：Unity Architect 建议通过 ScriptableObject 实现编辑时-运行时状态分离，倾向于在编辑器扩展中直接修改资产；Blender Add-on Engineer 坚持非破坏性原则，验证后必须用户主动确认才执行修改。 + - 当前观点：Blender 艺术家工作流强调"保留原始数据"——任何破坏性修改必须在 Dry-run 模式下预演，用户确认后才执行。 + - 对方观点：Unity Editor 工具倾向于"所见即所得"——编辑器内修改即为正式修改，ScriptableObject 负责持久化状态。 + - 协调建议：两者均强调"验证先行"——Blender Add-on Engineer 的非破坏性验证 + Unity Architect 的 SO 状态分离，本质上是从不同平台约束出发的等效安全实践。 diff --git a/wiki/sources/engineering-software-architect.md b/wiki/sources/engineering-software-architect.md new file mode 100644 index 00000000..d6c9ce6d --- /dev/null +++ b/wiki/sources/engineering-software-architect.md @@ -0,0 +1,58 @@ +--- +title: "Software Architect Agent Personality" +type: source +tags: [agent-personality, software-architecture, system-design, engineering] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/engineering/engineering-software-architect.md]] + +## Summary（用中文描述） +- 核心主题：软件架构与系统设计 Agent 的角色定义，专注于设计可维护、可扩展、符合业务领域的系统架构 +- 问题域：架构决策、模式选择、技术权衡、系统演进 +- 方法/机制：领域驱动设计（DDD）、边界上下文（bounded contexts）、架构决策记录（ADR）、C4 模型 +- 结论/价值：为 AI Agent 提供系统思维框架，强调权衡分析优先于最佳实践、领域优先于技术 + +## Key Claims（用中文描述） +- 最佳架构是团队能够实际维护的架构：架构不应过度设计，必须匹配团队能力 +- 每个抽象必须有复杂度理由：避免架构宇航员式的过度设计 +- 权衡优先于最佳实践：命名所放弃的，而非仅描述所获得的 +- 领域优先、技术其次：理解业务问题，再选工具 +- 可逆性很重要：优先选择易变更的决策，而非"最优"决策 +- 记录决策，而非仅记录设计：ADR 捕捉 WHY，而非 WHAT + +## Key Quotes +> "Designs systems that survive the team that built them. Every decision has a trade-off — name it." — 核心设计哲学 + +> "No architecture astronautics — Every abstraction must justify its complexity." — 关键规则 1 + +> "Domain first, technology second — Understand the business problem before picking tools." — 关键规则 3 + +> "Reversibility matters — Prefer decisions that are easy to change over ones that are 'optimal'." — 关键规则 4 + +## Key Concepts +- [[Bounded Contexts]]：领域驱动设计中划分业务边界的核心概念 +- [[Trade-off Analysis]]：架构决策中命名权衡而非仅列举优点的分析方法 +- [[Architecture Decision Record (ADR)]]：记录架构决策上下文、选项和理由的标准化模板 +- [[Modular Monolith]]：适合小型团队、不清晰边界的架构模式 +- [[Microservices]]：适合清晰领域、需要团队自治的架构模式 +- [[Event-Driven Architecture]]：适合松耦合、异步工作流的架构模式 +- [[CQRS]]：命令查询职责分离，适合读写不对称的系统 +- [[C4 Model]]：用四层图（C4：Context, Container, Component, Code）交流架构的标准化方法 +- [[Quality Attributes]]：可扩展性、可靠性、可维护性、可观测性等非功能需求 + +## Key Entities +- （本文档为通用 Agent 角色定义，未涉及特定人物、公司或产品） + +## Connections +- [[BackendArchitectWithMemory]] ← shares_design_philosophy ← [[SoftwareArchitectAgent]] +- [[WorkflowArchitect]] ← uses_ADR_pattern ← [[SoftwareArchitectAgent]] +- [[SpecializedWorkflowArchitect]] ← architectural_decision_making ← [[SoftwareArchitectAgent]] + +## Contradictions +- 与 [[UnityArchitect]] 冲突： + - 冲突点：架构约束与团队规模的关系 + - 当前观点（Software Architect）：最佳架构取决于团队能力； microservices 不适合小团队 + - 对方观点（Unity Architect）：针对特定技术平台（Unity）的架构师角色，可能倾向于选择特定技术栈而非纯权衡驱动 + - 注：两者领域不同（通用软件架构 vs 游戏引擎架构），冲突仅为框架层面的方法论差异 diff --git a/wiki/sources/godot-gameplay-scripter.md b/wiki/sources/godot-gameplay-scripter.md new file mode 100644 index 00000000..a32c6caf --- /dev/null +++ b/wiki/sources/godot-gameplay-scripter.md @@ -0,0 +1,79 @@ +--- +title: "Godot Gameplay Scripter Agent Personality" +type: source +tags: ["godot", "gdscript", "game-development", "agent-personality"] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/godot/godot-gameplay-scripter.md]] + +## Summary（用中文描述） +- 核心主题：Godot 4 游戏逻辑脚本专家 Agent 人格定义，强调以软件架构师的纪律性构建游戏系统 +- 问题域：如何用 GDScript 2.0 和 C# 构建类型安全、信号驱动、可组合的游戏玩法系统 +- 方法/机制：严格静态类型 + 信号架构 + 组合优于继承 + 正确的 Autoload 使用模式 + GDScript/C# 互操作规范 +- 结论/价值：提供了一套完整的 Godot 4 游戏开发规范，包括命名约定、代码模式、工作流程和性能指标 + +## Key Claims（用中文描述） +- GodotGameplayScripter Agent 以软件架构师的纪律性和独立游戏开发者的务实精神构建游戏玩法系统 +- GDScript 信号必须使用 snake_case 且携带类型化参数，C# 信号使用 PascalCase + EventHandler 后缀 +- 所有变量、函数参数和返回值必须显式类型化，禁止在生产代码中使用无类型 var +- 组合优于继承：通过子节点附加组件（如 HealthComponent）优于创建继承层级 +- Autoload 仅用于真正的跨场景全局状态，不得包含游戏逻辑 +- 场景必须可独立实例化，不得假设父节点类型或兄弟节点存在 + +## Key Quotes +> "Everything is a node — behavior is composed by adding nodes, not by multiplying inheritance depth" +> 核心哲学：一切皆为节点，行为通过添加节点组合，而非增加继承深度 + +> "Adding the type here catches this bug at parse time instead of 3 hours into playtesting" +> 类型安全即功能：在解析时捕获 bug，而非在测试 3 小时后发现 + +> "Don't add this to Player — make a component, attach it, wire the signal" +> 通信风格：组合优于捷径，永远不要把逻辑直接加到 Player 上，而是创建组件 + +> "GDScript signals use snake_case; if you're in C#, it's PascalCase with EventHandler" +> 语言感知：在 GDScript 中信号用 snake_case；在 C# 中用 PascalCase 加 EventHandler 后缀 + +## Key Concepts +- [[Signal-Driven Architecture]]：信号驱动架构——通过信号解耦系统，避免直接方法调用，信号必须携带类型化参数 +- [[Static Typing in GDScript 2.0]]：GDScript 2.0 静态类型——所有变量、参数、返回值必须显式类型化，使用 typed arrays +- [[Composition Over Inheritance]]：组合优于继承——通过附加子节点组件实现行为，而非创建继承层级 +- [[Event Bus Autoload]]：事件总线 Autoload——跨场景解耦通信的全局信号总线，只用于真正跨场景的事件 +- [[Type-Safe Signal Design]]：类型安全信号设计——信号命名遵循语言约定，参数必须类型化，连接时验证方法存在性 +- [[GDScript C# Interoperability]]：GDScript/C# 互操作——跨语言信号连接模式，类型转换和连接命名规范 + +## Key Entities +- [[GDScript 2.0]]：Godot 4 默认脚本语言，支持静态类型、装饰器、改进的信号系统 +- [[C# (Godot)]]：Godot 4 支持的 .NET 脚本语言，通过 GodotSharp bindings 与引擎交互 +- [[GDExtension]]：Godot 4 原生扩展机制，允许用 C++ 编写性能关键系统并暴露给 GDScript +- [[HealthComponent]]：健康组件示例——展示类型化信号声明、@export 属性、伤害/治疗逻辑的标准模式 +- [[EventBus]]：事件总线 Autoload——全局跨场景信号发射器，用于解耦通信 + +## Connections +- [[GDScript 2.0]] ← uses ← [[Static Typing in GDScript 2.0]] +- [[GDScript 2.0]] ← uses ← [[Type-Safe Signal Design]] +- [[C# (Godot)]] ← uses ← [[Type-Safe Signal Design]] +- [[EventBus]] ← implements ← [[Signal-Driven Architecture]] +- [[HealthComponent]] ← demonstrates ← [[Composition Over Inheritance]] +- [[GDExtension]] ← extends ← [[C# (Godot)]] + +## Contradictions +- 无已知冲突内容 + +## Technical Deliverables Summary + +### 核心代码模式 +- **Typed Signal (GDScript)**：`signal health_changed(new_health: float)` + `died.emit()` +- **Signal Bus Autoload**：`signal player_died` + `signal score_changed(new_score: int)` +- **Typed Signal (C#)**：`[Signal] public delegate void HealthChangedEventHandler(float newHealth)` +- **Composition Pattern**：`@onready var health: HealthComponent = $HealthComponent` +- **Typed Array**：`var _active_enemies: Array[EnemyBase] = []` +- **GDScript/C# Interop**：`health_component.HealthChanged.connect(_on_health_changed)`（PascalCase） + +### 质量指标 +- 生产代码零无类型 var 声明 +- 所有信号参数显式类型化，无 Variant +- 零运行时路径查找（所有 get_node 仅在 _ready 中通过 @onready） +- 组件节点 < 200 行，每个处理一个游戏关注点 +- 所有场景可独立运行（F6 测试通过） diff --git a/wiki/sources/godot-multiplayer-engineer.md b/wiki/sources/godot-multiplayer-engineer.md new file mode 100644 index 00000000..1f16e0fd --- /dev/null +++ b/wiki/sources/godot-multiplayer-engineer.md @@ -0,0 +1,55 @@ +--- +title: "Godot Multiplayer Engineer Agent Personality" +type: source +tags: [Godot, Multiplayer, Networking, Game Development, Godot 4, RPC, ENet, WebRTC] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/godot/godot-multiplayer-engineer.md]] + +## Summary（用中文描述） +- 核心主题：Godot 4 网络多人游戏专家 Agent，基于 MultiplayerAPI、MultiplayerSpawner、MultiplayerSynchronizer 和 RPC 机制实现实时多人游戏网络同步 +- 问题域：多人游戏权威模型设计、RPC 安全性、场景复制、延迟模拟测试、NAT 穿透与 WebRTC 集成 +- 方法/机制：通过 `set_multiplayer_authority()` 显式设置权威节点，RPC 调用模式（any_peer/authority/call_local）分层控制，MultiplayerSynchronizer 按需同步属性，MultiplayerSpawner 处理动态生成节点的网络复制 +- 结论/价值：提供生产级 Godot 4 多人游戏网络架构，覆盖服务器权威模型、RPC 安全审计、ENet/WebRTC 传输层配置、延迟测试与 matchmaking 集成 + +## Key Claims（用中文描述） +- Godot Multiplayer Engineer 通过 `set_multiplayer_authority()` 显式设置权威节点（而非依赖默认值 peer 1），确保每个动态生成节点的状态归属清晰 +- 所有游戏关键状态（位置、生命值、分数、物品状态）必须由服务器（peer 1）持有权威，客户端通过 RPC 发送输入请求，由服务器验证并更新权威状态 +- `@rpc("any_peer")` 允许任何对端调用，必须仅用于客户端→服务器请求，且函数体内必须进行服务器端验证和发送者 ID 检查，否则构成作弊漏洞 +- `MultiplayerSpawner` 是所有动态生成网络节点的唯一正确方式，手动 `add_child()` 会导致对端节点丢失同步 +- 所有 `@rpc("any_peer")` 函数必须进行服务器端验证（发送者 ID + 输入合理性检查），这是防止作弊的关键安全审计点 + +## Key Quotes +> "MANDATORY: The server (peer ID 1) owns all gameplay-critical state — position, health, score, item state" — 服务器权威模型强制规范 +> "Never use @rpc("any_peer") for functions that modify gameplay state without server-side validation inside the function body" — RPC 安全红线 +> "MultiplayerSynchronizer property paths must be valid at the time the node enters the tree — invalid paths cause silent failure" — Synchronizer 配置关键约束 +> "Don't add_child() networked nodes manually — use MultiplayerSpawner or peers won't receive them" — 场景复制核心原则 + +## Key Concepts +- [[MultiplayerAPI]]：Godot 4 核心网络 API，提供 `set_multiplayer_authority()`、`is_multiplayer_authority()`、RPC 调用和多人信号管理 +- [[Server-Authoritative Model]]：服务器权威模型 — 所有游戏关键状态由服务器持有权威，客户端发送输入请求，服务器验证后更新状态，防止作弊 +- [[RPC（Remote Procedure Call）]]：远程过程调用，通过 `@rpc()` 装饰器声明函数调用模式（any_peer/authority/call_local），实现跨网络的过程调用 +- [[MultiplayerSynchronizer]]：属性同步器 — 广播权威节点属性变更到所有对端，支持 ON_CHANGE 模式避免每帧同步 +- [[MultiplayerSpawner]]：场景生成器 — 在权威节点自动生成子场景并复制到所有对端，是动态生成网络节点的唯一正确方式 +- [[ENet]]：可靠 UDP 传输层，支持服务器/客户端两种模式，用于桌面平台的生产级网络连接 +- [[WebRTC]]：Web 实时通信协议，通过 `WebRTCPeerConnection` + `WebRTCMultiplayerPeer` 实现浏览器端 P2P 多人游戏和 NAT 穿透 +- [[Authority Model]]：权威模型 — 每个网络节点有且只有一个权威持有者（peer ID），只有权威才能修改该节点的关键状态 +- [[RPC Security Pattern]]：RPC 安全模式 — 所有 `any_peer` RPC 函数必须进行发送者 ID 验证和输入合理性检查，防止客户端作弊 + +## Key Entities +- [[Godot 4]]：开源游戏引擎，版本 4.x 引入了 MultiplayerAPI、MultiplayerSpawner、MultiplayerSynchronizer 构成完整的场景复制体系 +- [[Nakama]]：开源游戏服务器，用于 Godot 多人游戏的 matchmaking、大厅、排行榜和 DataStore 集成 + +## Connections +- [[godot-gameplay-scripter]] ← extends ← [[godot-multiplayer-engineer]]（多人游戏建立在 Godot 游戏逻辑脚本基础上） +- [[godot-shader-developer]] ← parallel ← [[godot-multiplayer-engineer]]（同属 Godot Game Dev 部门的不同专精方向） +- [[unity-multiplayer-engineer]] ← parallel ← [[godot-multiplayer-engineer]]（跨引擎多人游戏实现，核心概念一致但 API 不同） + +## Contradictions +- 与 [[unity-multiplayer-engineer]] 在权威模型实现细节上有差异： + - 冲突点：Unity 使用 NetworkTransform/NetworkVariable 隐式同步，Godot 使用 MultiplayerSynchronizer 显式配置 + - 当前观点：Godot 的显式权威模型（每节点 `set_multiplayer_authority()`）更透明，开发者对状态归属有完全控制 + - 对方观点：Unity 的隐式同步减少模板代码，但在复杂场景下权威归属不如 Godot 明确 +``` diff --git a/wiki/sources/godot-shader-developer.md b/wiki/sources/godot-shader-developer.md new file mode 100644 index 00000000..d8349600 --- /dev/null +++ b/wiki/sources/godot-shader-developer.md @@ -0,0 +1,50 @@ +--- +title: "Godot Shader Developer Agent Personality" +type: source +tags: [Godot, Shader, Game Development, GLSL, Visual Effects] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/godot/godot-shader-developer.md]] + +## Summary（用中文描述） +- 核心主题：Godot 4 渲染专家 Agent，使用 Godot 着色语言（GLSL-like）编写高性能 2D/3D 视觉效果着色器 +- 问题域：Godot 4 的 CanvasItem（2D）和 Spatial（3D）着色器开发、VisualShader 编辑器、后处理、性能优化 +- 方法/机制：通过 `shader_type` 声明、uniform 参数暴露、渲染器兼容性检查、纹理采样计数审计实现跨平台视觉效果 +- 结论/价值：为 Godot 4 游戏提供创作性正确且性能合规的着色器方案，覆盖 2D 精灵描边、3D 溶解/水面着色、全屏后处理 + +## Key Claims（用中文描述） +- Godot Shader Developer 通过 `shader_type` + GLSL-like 语法实现 2D CanvasItem 和 3D Spatial 着色器，在 Forward+ / Mobile / Compatibility 三种渲染器下提供差异化效果 +- VisualShader 编辑器适合艺术家快速迭代，代码着色器适合性能关键路径；两者互补而非替代 +- 所有 uniform 参数必须附带 hint（`hint_range`、`source_color`、`hint_normal` 等），否则 Inspector 无法正确显示 +- `SCREEN_TEXTURE` 采样会触发帧缓冲区复制，在移动端每帧 shader 中使用会严重影响性能 +- `discard` 在移动端不透明空间着色器中应替换为 Alpha Scissor，以保证性能合规 + +## Key Quotes +> "MANDATORY: Godot's shading language is not raw GLSL — use Godot built-ins (TEXTURE, UV, COLOR, FRAGCOORD) not GLSL equivalents" — Godot 4 着色语言核心规范 +> "8 texture samples in this fragment is 4 over mobile budget — here's a 4-sample version that looks 90% as good" — 移动端纹理采样性能审计原则 +> "Use VisualShader for effects artists need to extend — use code shaders for performance-critical or complex logic" — 工具选型原则 + +## Key Concepts +- [[CanvasItem Shader]]：Godot 2D/UI 着色器类型，使用 `shader_type canvas_item`，通过 `TEXTURE`、`UV`、`COLOR` 内置变量操作精灵和 UI 效果 +- [[Spatial Shader]]：Godot 3D 世界着色器类型，使用 `shader_type spatial`，通过 `ALBEDO`、`METALLIC`、`ROUGHNESS`、`NORMAL_MAP` 输出变量控制 PBR 材质 +- [[VisualShader]]：Godot 图形化着色器编辑器，将 GLSL 节点化，支持艺术家快速搭建材质变体；Group 和 Comment 节点用于组织复杂图 +- [[CompositorEffect]]：Godot 4 Forward+ 渲染器的全屏后处理扩展点，通过 GDScript `extends CompositorEffect` 实现自定义后处理 Pass +- [[Forward+ Renderer]]：Godot 4 高端渲染器，支持 `DEPTH_TEXTURE`、`SCREEN_TEXTURE`、`NORMAL_ROUGHNESS_TEXTURE` 全部特性 +- [[Mobile Renderer]]：Godot 4 中端渲染器，避免 `discard` 使用，优先 Alpha Scissor；纹理采样预算严格 +- [[Compatibility Renderer]]：Godot 4 最广泛支持渲染器，无 compute shader、无 `DEPTH_TEXTURE` canvas 采样、无 HDR 纹理 + +## Key Entities +- [[Godot]]：Juan Linietsky 和 Ariel Manzur 主导的开源游戏引擎，Godot 4 引入了 Forward+ 渲染器和重构的着色语言 +- [[GLSL]]：OpenGL 着色语言，Godot 着色语言基于 GLSL 但有自己的内置变量和 API（`texture()` vs `texture2D()`） + +## Connections +- [[Godot Gameplay Scripter]] ← collaborates_with ← [[Godot Shader Developer]]（Godot 游戏中脚本与着色器协同开发） +- [[Unity Shader Graph Artist]] ← compares_to ← [[Godot Shader Developer]]（两大主流游戏引擎的着色器方案对比） +- [[Technical Artist]] ← overlaps_with ← [[Godot Shader Developer]]（两者均涉及渲染技术与美术的桥梁工作） +- [[Godot Shader Developer]] ← uses ← [[VisualShader]]（VisualShader 作为快速原型工具） +- [[Godot Shader Developer]] ← targets ← [[Forward+ Renderer]] / [[Mobile Renderer]] / [[Compatibility Renderer]]（三种渲染器适配） + +## Contradictions +- 无已知冲突内容。 diff --git a/wiki/sources/roblox-avatar-creator.md b/wiki/sources/roblox-avatar-creator.md new file mode 100644 index 00000000..0aedeabd --- /dev/null +++ b/wiki/sources/roblox-avatar-creator.md @@ -0,0 +1,58 @@ +--- +title: "Roblox Avatar Creator Agent Personality" +type: source +tags: [] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/roblox-studio/roblox-avatar-creator.md]] + +## Summary（用中文描述） +- 核心主题：Roblox UGC（用户生成内容）化身系统专家 AI Agent 人格规范——从建模绑定到 Creator Marketplace 提交的完整 avatar pipeline +- 问题域：Roblox avatar 配件系统、Layered Clothing 分层服装、Creator Marketplace 合规审核、化身自定义 API +- 方法/机制：R15 骨骼权重系统；附件点（Attachment）定位；纹理规范（256-1024px PNG）；三角面数硬限制（配件≤4000、Bundle部件≤10000）；InnerCage/OuterCage 双笼系统 +- 结论/价值：提供可直接使用的 Luau 代码模块（HumanoidDescription、Layered Clothing cage setup、UGC Shop UI flow）和 Creator Marketplace 提交检查清单 + +## Key Claims（用中文描述） +- UGC 配件网格必须低于 4,000 三角面——超过此限制将导致自动拒绝（Roblox 强制规则） +- 所有 UGC 配件必须使用单个 UV 通道，UV 范围严格限制在 [0,1] 空间内——超出该范围将导致贴图采样错误 +- Layered Clothing 配件必须同时包含外层网格和 InnerCage 网格——缺失 InnerCage 将导致服装穿透过角色身体 +- 化身附件必须使用标准命名：HatAttachment、FaceFrontAttachment、LeftShoulderAttachment 等——命名错误导致跨 body type 附件失效 +- Creator Marketplace 商品名称必须准确描述商品——误导性名称将触发审核暂停 + +## Key Quotes +> "4,000 triangles is the hard limit — model to 3,800 to leave room for exporter overhead" — Roblox 网格三角面数规范：留 200 面余量防止导出器开销 +> "Looks great in Blender — now test it on Rthro Broad in a run cycle before submitting" — 测试原则：必须覆盖所有 5 种 body type 动画循环 +> "That logo will get flagged — use an original design instead" — 纹理内容规范：禁止任何商标或真实世界品牌 +> "Similar hats sell for 75 Robux — pricing at 150 without a strong brand will slow sales" — Creator Marketplace 定价策略：参考同类商品定价 + +## Key Concepts +- [[UGC]]: User Generated Content，Roblox 平台允许创作者发布和销售虚拟物品的经济系统 +- [[LayeredClothing]]: Roblox 分层服装系统，需要 Outer Mesh + InnerCage + OuterCage 三层 cage 网格实现变形 +- [[HumanoidDescription]]: Roblox 化身 API，通过 description.Apply() 方法应用全身装扮，支持 Shirt/Pants/Accessory 等属性 +- [[R15Rig]]: Roblox R15 avatar 骨骼系统，Layered Clothing 权重绑定到标准 R15 骨骼 +- [[CreatorMarketplace]]: Roblox 官方 UGC 交易平台，所有 UGC 商品需通过 Creator Dashboard 提交并通过自动化+人工审核 +- [[AttachmentPoint]]: Roblox 化身附件定位点，名称必须匹配 Roblox 标准（HatAttachment/FaceFrontAttachment 等） +- [[RthroBodyType]]: Roblox 瘦长型化身比例，与 Classic/R15 Normal 不同——需单独测试附件兼容性 + +## Key Entities +- [[Blender]]: 3D 建模软件，用于制作 UGC 配件网格和 cage 网格 +- [[RobloxStudio]]: Roblox 官方开发工具，通过 Avatar → Import Accessory 导入 UGC 物品 +- [[R15TestBodies]]: Roblox Studio 提供的 5 种测试化身预设：Young / Classic / Normal / Rthro Narrow / Rthro Broad +- [[DataStore]]: Roblox 服务器端持久化系统，用于存储玩家装扮数据 + +## Connections +- [[RobloxSystemsScripter]] ← game-dev-scope ← [[RobloxAvatarCreator]] +- [[RobloxExperienceDesigner]] ← player-economy ← [[RobloxAvatarCreator]] +- [[Blender]] ← mesh-pipeline ← [[RobloxAvatarCreator]] +- [[RobloxStudio]] ← asset-pipeline ← [[RobloxAvatarCreator]] +- [[CreatorMarketplace]] ← submission ← [[RobloxAvatarCreator]] +- [[R15Rig]] ← bone-weights ← [[RobloxAvatarCreator]] + +## Contradictions +- 与 [[UnityArchitect]] / [[UnityMultiplayerEngineer]] 冲突： + - 冲突点：角色自定义系统的实现路径差异 + - 当前观点（Roblox）：使用 HumanoidDescription API 实现服务端权威的化身自定义，数据通过 DataStore 持久化 + - 对方观点（Unity）：推荐客户端预测式角色定制，使用 LocalPlayer 状态缓存提升响应体验 + - 说明：此差异由平台架构约束决定——Roblox 的 LocalScript 不可写 DataStore，Unity 无此限制，均为各自平台最优解 diff --git a/wiki/sources/roblox-experience-designer.md b/wiki/sources/roblox-experience-designer.md new file mode 100644 index 00000000..e208500f --- /dev/null +++ b/wiki/sources/roblox-experience-designer.md @@ -0,0 +1,63 @@ +--- +title: "Roblox Experience Designer" +type: source +tags: [] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/roblox-studio/roblox-experience-designer.md]] + +## Summary（用中文描述） +- 核心主题：Roblox 平台原生体验设计师 Agent——专注于 Roblox 受众（9-17岁）的参与度循环设计、变现系统与玩家留存 +- 问题域：如何在 Roblox 平台设计可发现、有奖励感、符合平台政策的商业化体验 +- 方法/机制：DataStore 驱动进度系统、Game Pass/Developer Product/UGC 原生化变现、参与度阶梯（首次会话→每日留存→周留存）、每日奖励系统、分析事件追踪 +- 结论/价值：提供完整的 Roblox 原生 UX 和变现设计框架，涵盖技术代码示例（Lua）、入职流程三阶段设计、留存指标体系 + +## Key Claims（用中文描述） +- RobloxExperienceDesigner Agent：面向 9-17 岁受众的 Roblox 原生产品设计师，擅长参与度循环设计与合乎伦理的变现 +- 所有付费内容必须遵守 Roblox 政策——禁止 pay-to-win，免费体验必须完整 +- DataStore 存储玩家进度数据必须带重试逻辑，进度丢失是玩家永久流失的首要原因 +- Roblox 算法以同时在线人数、收藏量和访问量为信号——设计应鼓励组队游玩和分享 +- 每日奖励是投入产出比最高的留存功能，应在上线前实现 +- 入职流程第 1 分钟（0-60秒）是留存关键：玩家必须在首分钟内完成核心动作并获得成功体验 +- D1 留存率低于 25% 意味着入职流程未生效，需要审计前 5 分钟 + +## Key Quotes +> "Player-advocate, platform-fluent, retention-analytical, monetization-ethical" — RobloxExperienceDesigner 四大核心人格标签 +> "Loss of progression is the #1 reason players quit permanently" — DataStore 安全的首要原则 +> "If D1 is below 25%, the onboarding isn't landing — let's audit the first 5 minutes" — 留存分析与决策框架 +> "That feels like a dark pattern — let's find a version that converts just as well without pressuring kids" — 变现伦理准则 + +## Key Concepts +- [[EngagementLoop]]：参与度循环——从首次会话到每日返回再到周留存的完整阶梯设计，每层有清晰奖励闭环 +- [[DailyRewardSystem]]：每日奖励系统——基于连续登录天数的奖励阶梯（1-7天循环），驱动玩家习惯性返回 +- [[DataStoreDrivenProgression]]：DataStore 驱动进度——玩家投入（等级、道具、货币）持久化存储，创造不愿失去的沉没成本 +- [[GamePassMonetization]]：Game Pass 变现——永久性权益/功能通行证，通过 MarketplaceService 验证所有权 +- [[DeveloperProduct]]：开发者产品——可重复购买的消耗品（货币包、道具包），用于软货币变现 +- [[OnboardingFlow]]：入职引导流程——三阶段设计（60秒/5分钟/15分钟），最小化早期流失并通过游戏教学 +- [[RobloxAlgorithm]]：Roblox 推荐算法——以同时在线人数、收藏量、访问量为排名信号 +- [[AnalyticsService]]：分析服务——Roblox 内置 AnalyticsService，用于追踪自定义事件（D1/D7留存、首次购买、会话时长） +- [[SoftCurrencyFunnel]]：软货币首次购买漏斗——给新玩家足够货币以跨越首次购买心理障碍 +- [[PriceAnchoring]]：价格锚定——在标准选项旁展示高级选项，使标准选项显得实惠 + +## Key Entities +- [[RobloxExperienceDesigner]]：Agent 身份——Roblox 原生体验设计师，核心使命是设计让玩家返回、分享和付费的体验 +- [[RobloxPlatform]]：平台——主要受众 9-17 岁，提供 Game Pass/Developer Product/UGC 三大变现工具及推荐算法 +- [[MarketplaceService]]：市场服务——Lua API，用于验证 Game Pass 所有权和触发购买流程 +- [[DataStoreService]]：数据存储服务——Roblox 云端持久化 API，存储玩家进度数据（含每日奖励记录） +- [[AnalyticsService]]：分析服务——Roblox 内置事件追踪（无第三方依赖），在 Creator Dashboard 可见 +- [[VoiceChatService]]：语音聊天服务——用于社交/RP 类体验的空间语音集成 + +## Connections +- [[GameDesigner]] ← extends ← [[RobloxExperienceDesigner]]（Game Designer 的具体平台化实现） +- [[DailyRewardSystem]] ← depends_on ← [[DataStoreService]]（奖励记录依赖 DataStore 持久化） +- [[GamePassMonetization]] ← uses ← [[MarketplaceService]]（Game Pass 购买验证） +- [[OnboardingFlow]] ← feeds → [[AnalyticsService]]（入职完成事件上报） +- [[RobloxPlatform]] ← rewards → [[EngagementLoop]]（平台算法奖励参与度循环） + +## Contradictions +- 与 [[UnityArchitect]] 冲突： + - 冲突点：变现策略 + - 当前观点：Roblox 受众（9-17岁）必须遵守严格伦理变现——禁止 pay-to-win、人工稀缺、暗黑模式 + - 对方观点：Unity 平台面向更广泛受众，变现策略更灵活，可接受更强付费优势 diff --git a/wiki/sources/roblox-systems-scripter.md b/wiki/sources/roblox-systems-scripter.md new file mode 100644 index 00000000..5ccb10b5 --- /dev/null +++ b/wiki/sources/roblox-systems-scripter.md @@ -0,0 +1,55 @@ +--- +title: "Roblox Systems Scripter Agent Personality" +type: source +tags: [roblox, game-development, luau, client-server, datastore, security] +date: 2026-04-26 +--- + +## Source File +- [[raw/Agent/agency-agents/game-development/roblox-studio/roblox-systems-scripter.md]] + +## Summary（用中文描述） +- 核心主题：Roblox 平台工程专家的 Agent 人格定义，专注于 Luau 语言下的服务器权威架构与安全实现 +- 问题域：如何构建可扩展、防作弊、持久化数据安全的 Roblox 游戏体验 +- 方法/机制：服务器权威模型、RemoteEvent/RemoteFunction 安全验证、DataStore 重试与双保存机制、ModuleScript 模块化架构 +- 结论/价值：提供一套完整的 Roblox 系统脚本工程规范，涵盖从基础架构设计到高级并行 Luau 优化的全链路最佳实践 + +## Key Claims（用中文描述） +- 服务器是唯一的真相来源：客户端只接收视觉确认，不拥有任何游戏状态 +- 客户端通过 RemoteEvent/RemoteFunction 发送的请求，服务器必须重新验证，不能信任 +- DataStore 操作必须用 `pcall` 包装并实现指数退避重试，防止数据损坏 +- 玩家数据必须在 `PlayerRemoving` 和 `game:BindToClose()` 两处保存，缺一不可 +- 所有游戏系统必须放在 ModuleScript 中，Script/LocalScript 仅做引导，不含核心逻辑 + +## Key Quotes +> "Clients request, servers decide. That health change belongs on the server." — 客户端-服务器信任边界原则 +> "That save has no `pcall` — one DataStore hiccup corrupts the player's data permanently" — DataStore 安全核心警示 +> "RemoteFunction:InvokeClient() from the server — a malicious client can yield the server thread forever" — 危险操作警示 + +## Key Concepts +- [[Server-Authoritative Architecture]]：服务器权威模型——所有游戏逻辑状态由服务器拥有，客户端只显示状态，不决定状态 +- [[RemoteEvent Security]]：RemoteEvent 安全模式——FireServer 请求需在服务器端完整验证，不能信任客户端数据 +- [[DataStore Reliability]]：DataStore 可靠性模式——pcall 包装 + 指数退避重试 + 双保存点（PlayerRemoving + BindToClose） +- [[ModuleScript Architecture]]：ModuleScript 架构规范——所有逻辑放入 ModuleScript 返回表，Script/LocalScript 仅 bootstrap +- [[Parallel Luau]]：并行 Luau——使用 task.desynchronize() 和 Actor 模型实现真正的多线程脚本执行 +- [[Object Pooling]]：对象池模式——预实例化 effects 和 NPC，减少 GC 压力 +- [[UpdateAsync Atomic Pattern]]：UpdateAsync 原子写入——处理并发写入冲突，比 SetAsync 更安全 + +## Key Entities +- [[Roblox]]：游戏开发平台，提供 Roblox Studio、Lua 变体 Luau、DataStore 服务 +- [[Luau]]：Roblox 的脚本语言，是 Lua 的类型安全变体 +- [[DataStoreService]]：Roblox 数据持久化服务，用于保存玩家数据到云端 +- [[ReplicatedStorage]]：Roblox 实例容器，RemoteEvent 存放位置，客户端和服务器均可访问 +- [[ServerStorage]]：Roblox 实例容器，仅服务器可访问，用于存放核心模块 + +## Connections +- [[Roblox Experience Designer]] ← extends ← [[Roblox Systems Scripter]] +- [[Server-Authoritative Architecture]] ← foundational ← [[RemoteEvent Security]] +- [[DataStore Reliability]] ← depends_on ← [[Server-Authoritative Architecture]] + +## Contradictions +- 与 [[Unity Architect]] 冲突： + - 冲突点：客户端预测（Client Prediction）策略 + - 当前观点：Roblox Systems Scripter 建议简化场景下不做本地预测，所有状态由服务器驱动 + - 对方观点：Unity Multiplayer Engineer 建议使用服务器回滚式 client prediction 提升响应体验 + - 说明：两者平台不同，Roblox 的 RemoteEvent 架构天然适合服务器权威，Unity 的 Photon/Netcode 支持更灵活的预测策略 diff --git a/wiki/sources/unity-architect.md b/wiki/sources/unity-architect.md new file mode 100644 index 00000000..d403430e --- /dev/null +++ b/wiki/sources/unity-architect.md @@ -0,0 +1,58 @@ +--- +title: "Unity Architect" +type: source +tags: [] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/unity/unity-architect.md]] + +## Summary（用中文描述） +- 核心主题：Unity 游戏架构师 AI Agent 人格规范，专注于数据驱动、ScriptableObject（SO）优先的模块化可扩展架构 +- 问题域：如何构建避免"意大利面条式代码"的 Unity 项目，消除硬引用、单例滥用、God MonoBehaviour 等反模式 +- 方法/机制：ScriptableObject 事件通道（GameEvent）、RuntimeSet 无单例实体追踪、单一职责组件拆分、Inspector SO 引用连线、Custom PropertyDrawer 设计师赋能、Addressables 资源管理、Unity DOTS/ECS 混合架构 +- 结论/价值：通过 SO-first 设计，Unity 项目实现零 GameObject.Find()、每个 MonoBehaviour < 150 行、Prefab 场景无关自包含、设计师无需代码即可创建游戏变量/事件/运行时集合 + +## Key Claims（用中文描述） +- ScriptableObject-First 设计：所有共享游戏数据必须存于 ScriptableObject，绝不通过 MonoBehaviour 字段跨场景传递 +- GameEvent 事件通道：跨系统通信禁止使用 GetComponent<> 或单例，必须通过 SO 事件通道连线 +- RuntimeSet 无单例追踪：全局实体追踪使用 RuntimeSet : ScriptableObject 而非静态单例 +- 单一职责强制：每个 MonoBehaviour 只解决一个问题，若能用"and"描述则必须拆分 +- 反模式零容忍：God MonoBehaviour（500+ 行）、DontDestroyOnLoad 单例滥用、Update 内轮询逻辑均为禁止项 +- Unity DOTS 混合架构：性能关键系统迁移至 Entities（ECS），编辑器友好型游戏逻辑保留 MonoBehaviour + +## Key Quotes +> "Every MonoBehaviour solves one problem only — if you can describe a component with 'and,' split it." — 单一职责原则核心表述 +> "Treat every scene load as a clean slate — no transient data should survive scene transitions unless explicitly persisted via SO assets." — 场景卫生核心原则 +> "Designer-accessible: Non-technical team members can create new game variables, events, and runtime sets without touching code." — 设计师赋能核心价值 + +## Key Concepts +- [[ScriptableObject]]：Unity 资产形式的可序列化对象，用于存储共享数据、事件通道、运行时集合 +- [[RuntimeSet]]：继承 ScriptableObject 的泛型集合类型，用于全局追踪活跃实体而不依赖单例 +- [[GameEvent]]：SO 形式的事件通道（GameEvent : ScriptableObject），用于跨系统解耦通信 +- [[SingleResponsibilityPrinciple]]：每个 MonoBehaviour 只负责单一职责，超过 150 行即违反 +- [[EventDrivenArchitecture]]：事件驱动替代 Update() 内轮询，消除 GC 分配 +- [[DataDrivenDesign]]：数据驱动的模块化 Unity 架构设计理念 +- [[ScriptableObjectEventChannel]]：ScriptableObject 形式的 GameEvent 系统，通过 Raise/Register 模式实现松耦合 +- [[Addressables]]：Unity 资源管理系统，替代 Resources.Load()，支持细粒度内存控制和 DLC +- [[UnityDOTS]]：Data-Oriented Tech Stack，ECS + Job System + Burst Compiler，用于性能关键路径 +- [[EditorUtilitySetDirty]]：编辑器脚本修改 SO 数据后必须调用以确保序列化持久化 + +## Key Entities +- [[UnityArchitect]]：本文档定义的 AI Agent 人格，数据驱动模块化架构专家，精通 ScriptableObject、职责拆分、单例消除 +- [[UnityEditor]]：Unity 编辑器环境，ScriptableObject 通过 [CreateAssetMenu] 对设计师可见 +- [[UnityDOTS]]：Unity Data-Oriented Tech Stack（Entities、Jobs、Burst），用于 CPU 密集型批量操作 + +## Connections +- [[UnityArchitect]] ← builds_with ← [[ScriptableObject]] +- [[UnityArchitect]] ← extends ← [[UnityMultiplayerEngineer]]（网络层叠加 SO 架构） +- [[UnityArchitect]] ← complements ← [[UnityShaderGraphArtist]]（SO 数据驱动视觉资产） +- [[UnityArchitect]] ← complements ← [[UnityEditorToolDeveloper]]（Custom PropertyDrawer 赋能 SO 设计师体验） +- [[UnityArchitect]] ← builds_with ← [[UnityDOTS]]（性能关键路径使用 ECS 混合架构） + +## Contradictions +- 与 [[UnityMultiplayerEngineer]] 在客户端预测实现上存在框架差异： + - UnityArchitect 侧：NetworkVariable 通过 SO 引用在 MonoBehaviour 间传递状态 + - UnityMultiplayerEngineer 侧：NetworkVariable 直接挂载在 NetworkBehaviour 上 + - 两者均遵循服务器权威原则，差异在于 SO 层抽象程度，属架构风格差异而非绝对冲突 diff --git a/wiki/sources/unity-editor-tool-developer.md b/wiki/sources/unity-editor-tool-developer.md new file mode 100644 index 00000000..40548af3 --- /dev/null +++ b/wiki/sources/unity-editor-tool-developer.md @@ -0,0 +1,49 @@ +--- +title: "Unity Editor Tool Developer" +type: source +tags: [] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/unity/unity-editor-tool-developer.md]] + +## Summary（用中文描述） +- 核心主题：Unity 编辑器扩展开发工程师（Editor Tool Developer）的 AI Agent 人格规范——通过 EditorWindows、PropertyDrawers、AssetPostprocessors、Build Validators 等工具自动化团队工作流，减少人工错误 +- 问题域：游戏团队每日面临的素材导入错误、Inspector 数据误操作、命名规范失控、构建前人工检查等重复性工作 +- 方法/机制：基于 Unity Editor API 构建编辑器扩展工具，使用 `[SerializeField]` + `[MenuItem]` + `AssetPostprocessor` 模式实现自动化；通过 `Undo.RecordObject()` 保证操作可撤销；通过 `EditorUtility.DisplayProgressBar` 反馈长操作进度 +- 结论/价值：最佳工具是"隐形"的——在问题到达 QA 前自动拦截，在创意人员意识到需求前提前自动化 + +## Key Claims（用中文描述） +- UnityEditorToolDeveloper 通过 Editor 自动化，使艺术/设计/工程团队效率可量化提升 +- 所有 Editor 脚本必须置于 `Editor` 文件夹或使用 `#if UNITY_EDITOR` 保护——Editor API 调用进入运行时代码将导致构建失败 +- `EditorWindow` 必须通过 `[SerializeField]` 或 `EditorPrefs` 持久化状态，跨域重载不丢失 +- `AssetPostprocessor` 必须幂等——同一资源重复导入必须产生相同结果 +- `PropertyDrawer.OnGUI` 必须调用 `EditorGUI.BeginProperty` / `EndProperty` 以正确支持 Prefab Override UI +- 构建验证器失败时必须抛出 `BuildFailedException`，而非仅 `Debug.LogWarning` + +## Key Quotes +> "The best tools are invisible — they catch problems before they ship and automate the tedious so humans can focus on the creative." — UnityEditorToolDeveloper 核心理念 + +> "Can you Ctrl+Z that? No? Then we're not done." — Undo 是交付门槛，不支持撤销的工具不能发布 + +> "DX over raw power: The tool can do 10 things — let's ship the 2 things artists will actually use." — 开发者体验优先于功能堆砌 + +## Key Concepts +- [[EditorWindow]]：Unity 编辑器窗口扩展基类，用于构建团队可见的编辑器工具（资产审计、资源统计、验证面板） +- [[AssetPostprocessor]]：Unity 资源导入拦截器，在资源导入时自动强制执行命名规范、压缩设置、平台配置，确保每次导入结果一致且幂等 +- [[PropertyDrawer]]：自定义 Inspector 属性绘制器，扩展编辑器中序列化类型的显示方式，支持 MinMax Slider 等复合控件 +- [[AssemblyDefinitionFiles]]：`.asmdef` 文件用于在编译时强制 Editor/Runtime 程序集分离，防止 UnityEditor 命名空间泄漏到构建产物 +- [[BuildValidation]]：`IPreprocessBuildWithReport` 接口允许在构建前运行检查列表，失败时抛出 `BuildFailedException` 阻止打包 + +## Key Entities +- [[UnityEditorToolDeveloper]]：本 Source 对应的 AI Agent 人格——编辑器自动化专精，强调 DX、可量化的效率提升和隐形工具哲学 +- [[UnrealEditorToolDeveloper]]：对应 Unreal Engine 端的编辑器工具开发（比较视角） + +## Connections +- [[unity-editor-tool-developer]] ← game_dev_editor_extension ← [[game-designer]] +- [[unity-editor-tool-developer]] ← editor_automation ← [[unreal-systems-engineer]]（两者共享"构建前验证"模式） +- [[unity-editor-tool-developer]] ← tool_patterns ← [[technical-artist]]（Technical Artist 也负责编辑器工具和资产管线） + +## Contradictions +- 与 [[unreal-systems-engineer]] 在"编辑器工具 vs. 构建系统"边界上存在领域分工差异：Unity 侧通过 `IPreprocessBuildWithReport` 在构建前验证资源合规性；Unreal 侧通过 UAssetCheckConfig + UAssetCheckRule 在编辑器内实时检查。两者的目标相同（防止问题到达 QA），但实现时机和 API 不同——属互补而非冲突。 diff --git a/wiki/sources/unity-multiplayer-engineer.md b/wiki/sources/unity-multiplayer-engineer.md new file mode 100644 index 00000000..4784a94c --- /dev/null +++ b/wiki/sources/unity-multiplayer-engineer.md @@ -0,0 +1,64 @@ +--- +title: "Unity Multiplayer Engineer" +type: source +tags: [] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/unity/unity-multiplayer-engineer]] + +## Summary（用中文描述） +- 核心主题：Unity 多人游戏网络编程专家 Agent人格定义，涵盖 Netcode for GameObjects（NGO）、Unity Gaming Services（Relay/Lobby）集成、服务器权威模型、延迟补偿和状态同步等技术规范。 +- 问题域：如何为 Unity 游戏构建安全、抗作弊、延迟容忍的多人联网系统。 +- 方法/机制：服务器权威架构 + 客户端预测与调和 + RPC/NetworkVariable 分层设计 + UGS Relay/Lobby 匹配服务。 +- 结论/价值：提供完整的 Unity 多人游戏开发技术规范，包括网络代码模板、带宽管理策略、反作弊架构和高级性能优化方案。 + +## Key Claims（用中文描述） +- 服务器必须拥有所有游戏状态的权威真相——位置、生命值、分数、物品所有权，客户端仅发送输入。 +- NetworkVariable 用于持久化复制的状态，RPC 用于一次性事件，二者不可混用。 +- 客户端预测移动必须与服务器状态进行调和，当偏差超过阈值时强制回正。 +- Unity Relay 应用于所有玩家托管游戏，禁止直接 P2P 连接以保护主机 IP 安全。 +- 带宽管理：非关键状态更新（如血条、分数）应限流至最高 10Hz，避免每帧同步。 + +## Key Quotes +> "The client doesn't own this — the server does. The client sends a request." — 服务器权威原则 + +> "That NetworkVariable fires every frame — it needs a dirty check or it's 60 updates/sec per client" — 带宽控制原则 + +> "Design for 200ms — not LAN. What does this mechanic feel like with real latency?" — 延迟设计原则 + +> "If it persists, it's a NetworkVariable. If it's a one-time event, it's an RPC. Never mix them." — RPC vs Variable 原则 + +## Key Concepts +- [[ServerAuthority]]：服务器权威模型——服务器拥有所有游戏状态的最终真相，客户端仅发送输入请求。 +- [[ClientPrediction]]：客户端预测——客户端立即执行输入预测移动，再与服务器权威状态调和校正。 +- [[NetworkVariable]]: NGO 中用于持久化复制状态的类型，仅在值变化时触发网络同步。 +- [[ServerRpc]]: 客户端调用、服务器执行的 RPC，用于提交输入请求，服务器端必须验证所有输入。 +- [[ClientRpc]]: 服务器调用、所有客户端执行的 RPC，用于广播确认的游戏事件（如命中确认、技能激活）。 +- [[UnityRelay]]: Unity Gaming Services 的中继服务，解决 NAT 穿透问题，保护主机 IP 不暴露。 +- [[UnityLobby]]: Unity Gaming Services 的匹配大厅服务，仅存储元数据（玩家名、地图选择），不存储游戏状态。 +- [[LagCompensation]]: 延迟补偿机制——服务器在处理客户端输入时考虑网络延迟影响。 +- [[BandwidthManagement]]: 带宽管理——通过 dirty check、差分序列化、限流等策略控制网络流量。 +- [[AntiCheatArchitecture]]: 反作弊架构——所有游戏关键值必须经过服务器验证，客户端不可信。 + +## Key Entities +- [[UnityMultiplayerEngineer]]：本 Agent 角色定义——构建确定性、抗作弊、延迟容忍的 Unity 多人游戏系统的专家。 +- [[NetcodeForGameObjects]]：Unity 官方网络代码框架，提供 NetworkObject、NetworkVariable、ServerRpc、ClientRpc 等核心网络原语。 +- [[UnityGamingServices]]: Unity 云服务集合，包含 Relay（流量中继）和 Lobby（匹配大厅）两个多人游戏核心服务。 +- [[UnityTransport]]: Unity Netcode 的传输层，支持直连和 Relay 两种连接方式。 + +## Connections +- [[UnityMultiplayerEngineer]] ← extends ← [[NetcodeForGameObjects]] +- [[UnityMultiplayerEngineer]] ← depends_on ← [[UnityGamingServices]] +- [[ServerAuthority]] ← implements ← [[ClientPrediction]] +- [[ClientPrediction]] ← reconciles_with ← [[ServerAuthority]] +- [[UnityRelay]] ← enables ← [[ServerAuthority]] +- [[UnityLobby]] ← provides ← [[AntiCheatArchitecture]] + +## Contradictions +- 与 [[UnrealMultiplayerArchitect]] 潜在差异： + - 冲突点：客户端预测实现细节。 + - 当前观点（Unity）：使用 NetworkVariable + 自定义调和逻辑，在 LateUpdate 中检测并纠正客户端与服务端位置偏差。 + - 对方观点（Unreal）：使用更细粒度的帧缓冲和回滚机制。 + - 说明：两者均遵循服务器权威原则，差异源于底层网络框架设计哲学不同，两者可互补学习。 diff --git a/wiki/sources/unity-shader-graph-artist.md b/wiki/sources/unity-shader-graph-artist.md new file mode 100644 index 00000000..97052467 --- /dev/null +++ b/wiki/sources/unity-shader-graph-artist.md @@ -0,0 +1,59 @@ +--- +title: "Unity Shader Graph Artist" +type: source +tags: [] +date: 2026-04-26 +--- + +## Source File +- [[raw/Agent/agency-agents/game-development/unity/unity-shader-graph-artist.md]] + +## Summary（用中文描述） +- 核心主题：Unity Shader Graph Artist Agent 角色定义 —— 一个精通 Unity 渲染管线的专业 AI Agent，专注于 Shader Graph 可视化材质创作与 HLSL 性能优化 +- 问题域：游戏/实时渲染视觉效果开发、跨 URP/HDRP 管线的 Shader 创作规范与性能约束 +- 方法/机制：通过 Sub-Graph 模块化架构、Renderer Feature 自定义渲染通道、Shader Complexity Audit 复杂度审核流程，确保视觉效果与性能的平衡 +- 结论/价值：提供了一套完整的 Unity 渲染 Agent 工作体系，覆盖从设计简报到 Shader 交付、艺术家交接的全链路规范 + +## Key Claims（用中文描述） +- 所有 Shader Graph 必须使用 Sub-Graph 封装重复逻辑 —— 重复的节点簇是维护和一致性失败 +- URP 自定义通道必须使用 `ScriptableRendererFeature` + `ScriptableRenderPass` —— 禁止使用 `OnRenderImage`（仅限内置管线） +- HDRP 自定义通道使用 `CustomPassVolume` + `CustomPass` —— API 与 URP 不同，不可互换 +- 透明材质优先使用 Alpha Clipping 而非 Alpha Blend —— Alpha clipping 无过度绘制深度排序问题 +- 所有 Fragment Shader 必须在 Unity Frame Debugger 和 GPU Profiler 中完成性能分析后方可发布 + +## Key Quotes +> "Every Shader Graph must use Sub-Graphs for repeated logic — duplicated node clusters are a maintenance and consistency failure" — Shader Graph 架构强制规范 + +> "URP custom passes use `ScriptableRendererFeature` + `ScriptableRenderPass` — never `OnRenderImage` (built-in only)" — URP/HDRP 管线 API 差异说明 + +> "Mobile: max 32 texture samples per fragment pass; max 60 ALU per opaque fragment" — 移动端性能硬约束 + +## Key Concepts +- [[Shader Graph]]：Unity 可视化 Shader 编辑器，允许艺术家通过节点图创建材质，无需手写 HLSL +- [[Sub-Graph]]：Shader Graph 中的可复用子图模块，用于封装重复逻辑节点簇 +- [[URP (Universal Render Pipeline)]]：Unity 通用渲染管线，轻量级，跨平台支持 +- [[HDRP (High Definition Render Pipeline)]]：Unity 高清渲染管线，面向高端主机/PC 的 PBR 渲染 +- [[ScriptableRendererFeature]]：URP 自定义渲染通道系统，允许注入自定义全屏效果 +- [[HLSL]]：High-Level Shader Language，Shader Graph 编译的目标代码，可手写以实现极致性能 +- [[Alpha Clipping]]：透明裁剪渲染模式，通过像素丢弃实现透明效果，避免深度排序问题 +- [[Frame Debugger]]：Unity 内置帧调试工具，逐 draw call 分析渲染管线 +- [[RenderDoc]]：第三方 GPU 帧捕获工具，用于 Shader 调试和寄存器值检查 + +## Key Entities +- [[Unity Technologies]]：Unity Engine 开发商，提供 Shader Graph、URP、HDRP 等渲染系统 +- [[DissolveCore]]：Sub-Graph 封装示例，包含溶解效果的节点逻辑，可复用于多个角色材质 +- [[OutlineRendererFeature]]：自定义 URP Renderer Feature，实现描边效果的 C# 类 +- [[CustomLit.hlsl]]：URP 兼容的 PBR 自定义 Shader 示例，展示完整的 HLSL 编写规范 + +## Connections +- [[UnityShaderGraphArtist]] ← authored_by ← [[TechnicalArtist]]（Technical Artist 可能指导或审查 Shader Graph Artist 的输出） +- [[Shader Graph]] ← requires ← [[URP / HDRP]]（Shader Graph 必须在正确的渲染管线下创作） +- [[Sub-Graph]] ← enables ← [[Shader Graph]]（Sub-Graph 是 Shader Graph 模块化的基础） +- [[ScriptableRendererFeature]] ← part_of ← [[URP]]（自定义渲染通道是 URP 的扩展机制） + +## Contradictions +- 与 [[UnrealTechnicalArtist]] 关于渲染管线选择： + - 冲突点：Unreal 使用 Material Editor + Custom Node（HLSL）方案，Unity 使用 Shader Graph + Sub-Graph 方案 + - 当前观点：Unity Shader Graph Artist 认为 Shader Graph 应为艺术家首选，HLSL 仅用于性能关键路径 + - 对方观点：Unreal Technical Artist 认为 HLSL 编码在所有情况下都是首选方案 + - 说明：两者均为各自平台的最佳实践，冲突源于平台差异而非绝对优劣 diff --git a/wiki/sources/unreal-multiplayer-architect.md b/wiki/sources/unreal-multiplayer-architect.md new file mode 100644 index 00000000..cc8d063f --- /dev/null +++ b/wiki/sources/unreal-multiplayer-architect.md @@ -0,0 +1,57 @@ +--- +title: "Unreal Multiplayer Architect" +type: source +tags: [game-development, unreal-engine, networking, multiplayer, ue5] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/unreal-engine/unreal-multiplayer-architect.md]] + +## Summary（用中文描述） +- 核心主题：UE5多人游戏网络架构专家角色定义——构建服务器权威模型、延迟容忍、作弊防护的多人游戏系统 +- 问题域：Actor复制、网络预测、RPC安全验证、带宽优化、GAS复制、专用服务器构建 +- 方法/机制：Server-authoritative架构、UFUNCTION(Server, Reliable, WithValidation)、GetLifetimeReplicatedProps、Replication Graph、双路径GAS初始化 +- 结论/价值：提供生产级UE5多人游戏网络系统的完整技术方案，涵盖从基础复制到高级预测框架的全栈实现 + +## Key Claims（用中文描述） +- 服务器必须拥有所有游戏状态变化的执行权威，客户端仅发送RPC请求，由服务器验证后复制 +- 所有游戏逻辑相关的Server RPC必须实现WithValidation，不得省略_Validate()实现 +- 网络复制频率应按Actor类型差异化配置，默认100Hz过高，大多数Actor仅需20-30Hz +- GAS的AbilitySystemComponent初始化必须在PossessedBy（服务器路径）和OnRep_PlayerState（客户端路径）两个入口点分别执行 +- 专用服务器构建必须使用Linux平台+Shipping配置+Cooked内容 + +## Key Quotes +> "The server owns truth. The client requests it — the server decides." — 权威模型的核心原则 +> "WithValidation tag is not optional for any game-affecting RPC" — 安全验证的强制性要求 +> "Bandwidth per player < 15KB/s at maximum player count" — 性能基准指标 +> "Every Server RPC needs a `_Validate`. No exceptions. One missing is a cheat vector." — 作弊防护的非妥协立场 + +## Key Concepts +- [[ServerAuthoritativeModel]]：服务器权威模型——服务器模拟真实状态，客户端预测并对账，所有游戏逻辑在服务器执行 +- [[ActorReplication]]：Actor复制——UPROPERTY(Replicated)将状态从服务器同步到客户端，支持ReplicatedUsing触发RepNotify +- [[RPC]]：远程过程调用——Client/Server/NetMulticast三种RPC类型，Server RPC必须带验证 +- [[NetworkPrediction]]：网络预测——客户端本地预测操作，服务器确认后校正，减少感知延迟 +- [[ReplicationGraph]]：复制图——空间分区优化，仅向相关客户端复制区域内的Actor，降低带宽 +- [[GAS]]：Gameplay Ability System——UE5技能系统，支持复制和预测的技能与属性管理 +- [[DedicatedServer]]：专用服务器——无图形界面的纯服务器实例，处理所有游戏逻辑 +- [[NetworkRelevancy]]：网络相关性——根据客户端视角决定哪些Actor需要复制，节省带宽 +- [[NetMulticast]]：多播RPC——服务器向所有客户端广播事件，用于仅表现层效果 + +## Key Entities +- [[GameMode]]：服务器独有（永不复制）——生成逻辑、规则仲裁、胜负条件判定 +- [[GameState]]：复制到所有客户端——共享世界状态（回合计时器、队伍分数等） +- [[PlayerState]]：复制到所有客户端——每玩家公开数据（名称、延迟、击杀数） +- [[PlayerController]]：仅复制到拥有客户端——输入处理、摄像机、HUD控制 +- [[AbilitySystemComponent]]：GAS核心组件——管理技能和属性，必须正确配置复制 +- [[ReplicationGraph]]：UE5复制图插件——用空间分区替代默认扁平相关性模型 + +## Connections +- [[GameMode]] ← spawns + governs ← [[GameState]] +- [[PlayerController]] ← possesses ← [[PlayerState]] +- [[GameplayAbilitySystem]] ← depends_on ← [[ActorReplication]] +- [[NetworkPrediction]] ← extends ← [[ActorReplication]] +- [[DedicatedServer]] ← hosts ← [[GameMode]] + +## Contradictions +- 与现有Wiki内容暂无冲突——本页面为独立技术领域（UE5网络架构） diff --git a/wiki/sources/unreal-systems-engineer.md b/wiki/sources/unreal-systems-engineer.md new file mode 100644 index 00000000..44d72118 --- /dev/null +++ b/wiki/sources/unreal-systems-engineer.md @@ -0,0 +1,54 @@ +--- +title: "Unreal Systems Engineer" +type: source +tags: [] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/unreal-engine/unreal-systems-engineer.md]] + +## Summary（用中文描述） +- 核心主题：Unreal Engine 5 系统架构师 AI Agent 人格规范——C++/Blueprint 边界决策、性能优化、网络就绪游戏系统构建 +- 问题域：AAA 级 UE5 游戏项目中的技术架构决策、性能瓶颈规避、网络复制可靠性保障 +- 方法/机制：C++/Blueprint 分层架构（Tick 逻辑必须 C++）、GAS 网络复制配置、Nanite 实例预算管理、智能指针内存安全、Unreal Build System 反射宏规范 +- 结论/价值：建立了一套完整的 UE5 系统工程师能力标准，涵盖从内存管理到高级渲染的 AAA 级开发规范 + +## Key Claims（用中文描述） +- Tick 逻辑必须实现于 C++——Blueprint VM 开销与缓存未命中在每帧调用频率下构成性能风险 +- Nanite 单场景硬上限 1600 万实例——开放世界项目需提前规划实例预算 +- 所有 UObject 派生指针必须声明 UPROPERTY()——缺失将导致垃圾回收意外销毁 +- GAS 网络复制必须通过 UAbilitySystemComponent——禁止手动复制技能状态 +- FGameplayTag 优于字符串——标签支持层级结构、复制安全、全局搜索 + +## Key Quotes +> "Any logic that runs every frame (`Tick`) must be implemented in C++ — Blueprint VM overhead and cache misses make per-frame Blueprint logic a performance liability at scale." — UnrealSystemsEngineer 核心原则 + +> "Nanite supports a hard-locked maximum of 16 million instances in a single scene — plan large open-world instance budgets accordingly." — Nanite 实例预算警告 + +> "All `UObject`-derived pointers must be declared with `UPROPERTY()` — raw `UObject*` without `UPROPERTY` will be garbage collected unexpectedly." — 内存安全核心规范 + +## Key Concepts +- [[GAS-Gameplay-Ability-System]]：UE5 技能与属性管理框架，通过 UGameplayAbility/UAttributeSet/UAbilitySystemComponent 实现网络就绪的技能系统 +- [[Nanite]]：UE5 虚拟几何体系统，支持自动 LOD 和海量实例化渲染，单场景上限 1600 万实例 +- [[LumenGI]]：UE5 全局光照系统（源文档关联提及，未独立建页） +- [[Chaos-Physics]]：UE5 物理与破坏系统框架（源文档 Advanced Capabilities 提及，建议后续独立建页） +- [[Mass-Entity]]：Unreal ECS 实现，通过 UMassEntitySubsystem 处理海量 NPC/投射物/人群代理 +- [[Lyra-Gameplay-Framework]]：Epic 的模块化游戏框架模式，GameFeatureAction 运行时组件注入 + +## Key Entities +- [[UnrealEngine5]]：Epic Games 开发的游戏引擎，提供 C++/Blueprint 双轨开发、Gas、Nanite、Lumen 等全栈工具链 +- [[UnrealMultiplayerArchitect]]：多人网络架构师 Agent，与本 Agent 在网络就绪系统设计上存在协作关系（GAS 配置中涉及网络复制） +- [[UnrealTechnicalArtist]]：视觉系统工程师 Agent，与本 Agent 在 Nanite 几何优化上存在协作关系（Technical Artist 负责 Nanite 资产验证） + +## Connections +- [[UnrealMultiplayerArchitect]] ← shares_gas_architecture_with ← [[UnrealSystemsEngineer]] +- [[UnrealTechnicalArtist]] ← shares_nanite_optimization_with ← [[UnrealSystemsEngineer]] +- [[UnrealEngine5]] ← provides_engine_capabilities_to ← [[UnrealSystemsEngineer]] + +## Contradictions +- 与 [[UnrealMultiplayerArchitect]] 在 GAS 职责边界： + - 冲突点：GAS 配置中技能系统实现与网络复制配置的职责归属 + - 当前观点（本 Agent）：系统架构师负责 UGameplayAbility/UAttributeSet C++ 实现和网络复制配置 + - 对方观点：网络架构师负责 RPC 通信层面和 Server Authoritative 状态同步 + - 解决方向：两者互补——系统工程师构建 GAS 内部逻辑，网络架构师确保 RPC 层安全调用 GAS diff --git a/wiki/sources/unreal-technical-artist.md b/wiki/sources/unreal-technical-artist.md new file mode 100644 index 00000000..af93aabd --- /dev/null +++ b/wiki/sources/unreal-technical-artist.md @@ -0,0 +1,58 @@ +--- +title: "Unreal Technical Artist" +type: source +tags: ["game-development", "unreal-engine", "technical-art", "vfx", "procedural-generation"] +date: 2026-04-26 +--- + +## Source File +- [[Agent/agency-agents/game-development/unreal-engine/unreal-technical-artist.md]] + +## Summary（用中文描述） +- 核心主题：Unreal Engine 5 视觉系统工程师的 AI Agent 人格定义，专注于 UE5 的材质编辑器、Niagara VFX、PCG 程序化内容生成和美术-引擎管线 +- 问题域：如何在 AAA 级项目中，在硬件预算内交付高质量的视觉效果；如何建立可复用、可扩展的视觉工具链 +- 方法/机制： + - Material Editor 规范：Material Functions 复用原则、Material Instances 变体机制、Quality Switch 质量分层 + - Niagara VFX 规范：GPU/CPU 模拟选择、粒子数量限制、Scalability 分级预设 + - PCG 规范：确定性图生成、地形采样、密度过滤、Nanite 优化 + - LOD 与剔除：Nanite 策略、Cull Distance Volumes、HLOD 配置 +- 结论/价值：定义了完整的 UE5 视觉技术交付标准，覆盖从材质到 VFX 到程序化场景的全管线 + +## Key Claims（用中文描述） +- 可复用逻辑必须封装为 Material Functions，绝不在多个 Master Material 间重复节点簇 +- 所有粒子系统必须设置 `Max Particle Count`，禁止无限粒子 +- PCG 图是确定性的：相同输入参数始终产生相同输出 +- 所有 PCG 放置的资产在符合条件时必须启用 Nanite +- Substrate（UE5.3+）可实现多层物理材质叠加，替换传统 SSS workaround + +## Key Quotes +> "Reusable logic goes into Material Functions — never duplicate node clusters across multiple master materials" — Material Editor 核心原则 +> "CPU simulation for < 1000 particles; GPU simulation for > 1000" — Niagara GPU/CPU 选择标准 +> "PCG graphs are deterministic: same input graph and parameters always produce the same output" — PCG 确定性保证 +> "All Nanite-ineligible meshes require manual LOD chains with verified transition distances" — LOD 验收标准 +> "Every Static Switch doubles shader permutation count — audit before adding" — 材质复杂度控制 + +## Key Concepts +- [[MaterialFunction]]：UE5 材质系统中可复用的节点逻辑封装单元，用于消除跨材质重复逻辑 +- [[NiagaraVFX]]：UE5 新一代粒子和 VFX 系统，支持 GPU/CPU 模拟分离与 Scalability 分级 +- [[PCG]]：Procedural Content Generation，UE5 程序化内容生成框架，通过图节点控制开放世界资产分布 +- [[Nanite]]：UE5 虚拟几何体系统，支持自动 LOD 和海量实例化渲染 +- [[Substrate]]：UE5.3+ 多层材质系统，支持物理正确的层叠材质（湿涂层/泥土/岩石），替代传统 SSS workaround +- [[LOD]]：Level of Detail，根据距离切换网格精度，是开放世界性能优化的基础机制 +- [[QualitySwitch]]：UE5 材质节点，支持在单一材质图中定义移动/主机/PC 三档质量层级 + +## Key Entities +- [[UnrealEngine5]]：Epic Games 开发的游戏引擎，提供 Material Editor、Niagara、PCG、Nanite 等视觉工具链 +- [[UnrealInsights]]：UE5 性能分析工具，用于识别渲染性能瓶颈 +- [[WorldPartition]]：UE5 开放世界管理系统，与 HLOD 和 PCG 流式加载协同工作 + +## Connections +- [[MaterialFunction]] ← 核心依赖 ← [[UnrealTechnicalArtist]] +- [[NiagaraVFX]] ← 核心依赖 ← [[UnrealTechnicalArtist]] +- [[PCG]] ← 核心依赖 ← [[UnrealTechnicalArtist]] +- [[UnrealEngine5]] ← 基于 ← [[UnrealTechnicalArtist]] +- [[UnrealWorldBuilder]] ← 协同 ← [[UnrealTechnicalArtist]] +- [[UnrealSystemsEngineer]] ← 协同 ← [[UnrealTechnicalArtist]]（技术艺术家负责视觉，系统工程师负责底层） + +## Contradictions +- 暂无冲突内容 diff --git a/wiki/sources/unreal-world-builder.md b/wiki/sources/unreal-world-builder.md new file mode 100644 index 00000000..e2d43527 --- /dev/null +++ b/wiki/sources/unreal-world-builder.md @@ -0,0 +1,50 @@ +--- +title: "Unreal World Builder Agent Personality" +type: source +tags: ["unreal-engine", "open-world", "ue5", "world-partition", "game-development"] +date: 2026-04-26 +--- + +## Source File +- [[raw/Agent/agency-agents/game-development/unreal-engine/unreal-world-builder.md]] + +## Summary（用中文描述） +- 核心主题：Unreal Engine 5 开放世界环境构建 Agent 的角色定义与工作规范 +- 问题域：大型开放世界游戏（4km² ~ 64km²）的环境流送、渲染优化、内容生成等技术挑战 +- 方法/机制：World Partition 分区流送、Landscape 地形系统、PCG 程序化内容生成、HLOD 层级 LOD、Nanite 虚拟几何体、RVT 运行时虚拟纹理 +- 结论/价值：提供了一套完整的 UE5 开放世界技术交付标准，覆盖从网格规划到性能验证的全流程 + +## Key Claims（用中文描述） +- World Partition 格子大小必须由目标流送预算决定：密集城区用 64m、空旷地形用 128m、沙漠/海洋用 256m+ +- Landscape 材质超过 2 层时必须启用 Runtime Virtual Texturing（RVT），否则产生每像素层混合成本爆炸 +- HLOD 必须为所有 500m 以外可见区域生成，未构建 HLOD 会导致远距离 Actor 数量激增 +- PCG 大规模植被必须使用预烘焙输出，运行时 PCG 仅限 1km² 以下小区域 +- 大世界坐标（LWC）必须在任何轴超过 2km 的世界启用，否则约 20km 后出现浮点精度错误 + +## Key Quotes +> "Cell size must be determined by target streaming budget — smaller cells = more granular streaming but more overhead" — World Partition 配置核心原则 +> "HLOD must be built for all areas visible at > 500m camera distance — unbuilt HLOD causes actor-count explosion at distance" — HLOD 必建规则 +> "Foliage Tool (legacy) is for hand-placed art hero placement only — large-scale population uses PCG" — PCG 替代 Foliage Tool 的使用场景 +> "Enable Large World Coordinates for worlds > 2km in any axis — floating point precision errors become visible at ~20km without LWC" — LWC 启用阈值 + +## Key Concepts +- [[WorldPartition]]: UE5 的开放世界分区管理系统，将世界划分为格子，支持按需流送 +- [[Landscape]]: UE5 地形系统，支持多层混合烘焙和运行时虚拟纹理 +- [[PCG]]: Procedural Content Generation，程序化内容生成，用于大规模植被和环境资产放置 +- [[HLOD]]: Hierarchical Level of Detail，层级 LOD，通过网格合并减少远距离 Draw Call +- [[Nanite]]: UE5 虚拟化几何体系统，处理大规模几何细节，支持数百万实例 +- [[RuntimeVirtualTexturing]]: RVT，运行时虚拟纹理，消除地形层混合的像素级计算开销 +- [[LargeWorldCoordinates]]: LWC，双精度坐标系统，解决超大世界浮点精度问题 + +## Key Entities +- [[UnrealEngine5]]: 开发平台，UE5 提供 World Partition、Nanite、LWC 等开放世界基础设施 +- [[EpicGames]]: Unreal Engine 发行商，World Partition 和 Nanite 均为 Epic 内部开发的技术 + +## Connections +- [[UnrealSystemsEngineer]] ← skill_overlap ← [[UnrealWorldBuilder]]（共享 World Partition 流送基础设施） +- [[UnrealTechnicalArtist]] ← extends ← [[UnrealWorldBuilder]]（共享 Landscape 材质与 RVT 技术） +- [[UnrealWorldBuilder]] ← depends_on ← [[Nanite]]（PCG 植被依赖 Nanite 优化实例渲染） +- [[UnrealWorldBuilder]] ← depends_on ← [[HLOD]]（开放世界远距离渲染优化依赖 HLOD 系统） + +## Contradictions +- 未发现与现有 Wiki 内容的冲突。