20 KiB
Thread: ShrinkSDKUnity
Alias
ShrinkSDKUnity
Status: OPEN
Goal
持续推进 D:\UnityBuilds\ShrinkSDK 的 SDK 基础设施,重点围绕:
ShrinkModFrameworkShrinkNetwork- 独立服务器能力
- 权限、RPC、传输层
Context
Created from conversation on 2026-04-05.
本线程当前已经落地:
.planning/codebase/中文代码库地图Assets/Modules/ShrinkModFramework/- 模组声明、依赖声明、生命周期
RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)自动启动- 外部 DLL 热插拔
- Harmony 自动补丁接入
Assets/Modules/ShrinkNetwork/[ShrinkNetworkMessage][ShrinkNetworkSubscriber][ShrinkNetworkSubscribe]RpcAsync- 权限模型
ShrinkNetworkAuthority / ShrinkNetworkPeerKind / Permission ShrinkJsonNetworkSerializerShrinkMessagePackNetworkSerializerShrinkLoopbackTransportShrinkTcpClientTransportShrinkKcpClientTransportShrinkKcpPeerShrinkKcpTransportOptions
GeneratedServers/ShrinkNetwork.ServerHost/- 独立 .NET 控制台服务器
TcpServerTransportKcpServerTransport- 同时监听 TCP
17001与 KCP17002
This Round
这一轮新增与修复:
- 重构
ShrinkNetwork目录结构:Runtime/CoreRuntime/MetadataRuntime/RoutingRuntime/SerializationRuntime/Transport/*Editor/Scaffolding
- 删除仓库内固定参考工程,改为插件模板 + 生成式独立服务器工程
- 独立服务器生成器支持扫描:
[ShrinkNetworkMessage]- 显式
RegisterMessage<T>(opcode, route)
- 新增显式状态同步范式:
ShrinkNetworkStateSyncAttributeShrinkNetworkStateSyncRole
- LAN 演示消息补齐:
[ShrinkNetworkMessage][ShrinkNetworkStateSync("lan", role)]
opcode/route冲突改为生成阶段直接报错,不由框架静默兜底ShrinkNetworkService.BindTransport(...)自动接入可选桥接:- 自动注册
ShrinkNetwork.Integration.EventBus BindTransport(null)自动解绑
- 自动注册
ShrinkNetwork.Integration.EventBus增加更易用扩展:session.PublishEventAsync(...)session.RequestEventAsync(...)service.BroadcastEventAsync(...)service.UseEventBusBridge(...)
ShrinkEmbeddedHostNetworkDemoSceneController去掉手工RegisterService(...)- 统一重写 README:
Assets/Modules/ShrinkNetwork/README.mdAssets/Modules/ShrinkNetwork.Integration.EventBus/README.mdAssets/Modules/ShrinkDataSaver.Integration.EventBus/README.md
This Round Update
继续补齐的内容:
ShrinkNetwork的 RPC 关联 id 从裸int rpcId重构为强类型ShrinkRequestTokenShrinkRpcCallOptions增加:RequestTokenOverrideDebugLabel
ShrinkNetworkPacket / ShrinkNetworkContext / ShrinkNetworkRouter / ShrinkNetworkService全链路改用RequestTokenShrinkNetwork.Integration.EventBus的请求结果调用默认带事件类型DebugLabel- TCP 客户端在“远端正常关闭连接”时不再刷异常堆栈,降级为 warning
- 独立服务器生成器继续升级:
- 不只识别
[ShrinkNetworkEvent] - 还会区分:
- 广播型网络事件
- 远端裁决网络事件
- 增量网络事件
- 对非状态同步范式接管的网络事件消息,自动生成 handler 模板并自动注册
RegisterHandler(...)
- 不只识别
- 同步更新当前生成产物:
GeneratedServers/ShrinkNetwork.ServerHost/Generated/UnityGeneratedServerHandlers.g.csGeneratedServers/ShrinkNetwork.ServerHost/Generated/UnityGeneratedServerModule.g.csGeneratedServers/ShrinkNetwork.ServerHost/Generated/UNITY_GENERATED_SERVER_SCAFFOLD.md
- 模板说明补齐:
Assets/Modules/ShrinkNetwork/Editor/Scaffolding/ServerProjectTemplate/README.md.txtAssets/Modules/ShrinkNetwork/README.md
- 商业级可用性第一轮硬化:
ShrinkNetworkService/ShrinkNetworkSession改为并发安全集合,断线时自动失败对应的挂起 RPC- TCP 客户端 / 服务端补齐最大包长保护,避免远端伪造长度直接触发大内存分配
- 运行时
ShrinkKcpServerTransport补齐远端地址校验,并把会话conversationId改为随机分配 - 独立服务器模板与当前
GeneratedServers宿主改为“默认拒绝匿名登录”,只有显式允许时才在缺少令牌时放行 - 同步更新:
Assets/Modules/ShrinkNetwork/Editor/Scaffolding/ServerProjectTemplate/*GeneratedServers/ShrinkNetwork.ServerHost/*
- 商业级可用性第二轮硬化:
ShrinkNetworkPacket增加ProtocolVersion / SchemaVersionShrinkNetworkService增加协议版本窗口校验,必要时通过IShrinkNetworkSessionControlTransport主动断开违规会话ShrinkNetworkService增加基础指标快照:- 会话连接/断开
- 收发包与字节数
- RPC 发起/完成/超时/取消/失败
- 协议违规、权限拒绝、处理器异常、未知 opcode、分发 miss、反序列化失败
- 独立服务器宿主新增:
ServerHostOptions.MinProtocolVersion / MaxProtocolVersionServerHostOptions.MinSchemaVersion / MaxSchemaVersionServerHostOptions.DisconnectOnProtocolViolationServerHostOptions.DiagnosticsLogIntervalSeconds
Program.cs会定期输出指标摘要,并在Ctrl+C前打印最后一份快照
Verified
已做实际验证:
dotnet build .\\Assembly-CSharp.csproj /m:1 -p:BaseIntermediateOutputPath=Temp\\CliObj\\Assembly-CSharp\\dotnet build .\\Assembly-CSharp-Editor.csproj /m:1 -p:BaseIntermediateOutputPath=Temp\\CliObj\\Assembly-CSharp-Editor\\dotnet build .\\GeneratedServers\\ShrinkNetwork.ServerHost\\ShrinkNetwork.ServerHost.csproj /nr:falsedotnet build .\\ShrinkNetwork.Runtime.csproj /m:1dotnet build .\\ShrinkSDK.sln /m:1
说明:
- Unity 侧当前编译为 0 warning / 0 error
- 当前
GeneratedServers\\ShrinkNetwork.ServerHost可编译通过,但在net8.0宿主侧仍有一批既有 nullable warnings - 当前
GeneratedServers\\ShrinkNetwork.ServerHost也已手工同步到新生成器语义 - 这轮没有做 Unity 编辑器内按钮点击与 PlayMode 回归
- 商业级硬化这一轮已额外验证:
dotnet build .\\Assembly-CSharp.csproj /m:1 -p:BaseIntermediateOutputPath=Temp\\CliObj\\Assembly-CSharp\\dotnet build .\\GeneratedServers\\ShrinkNetwork.ServerHost\\ShrinkNetwork.ServerHost.csproj /nr:falsedotnet build .\\ShrinkSDK.sln /m:1
Notes
D:\UnityBuilds\ShrinkSDK是根 Git 仓库;EventBus、DataSaver 与 DataSaver.EventBus 已从 gitlink/嵌套仓库改为根仓库直接跟踪,干净克隆可恢复完整源码。- 当前唯一架构文档是根
DESIGN.md;Cordis 完成态和旧.planning/codebase地图已归档到Docs/Archive/。 - 独立服务器生成器已改为扫描 Unity 编译后的 Player 程序集语义,并用 SHA-256 清单保护模板托管文件。
- 当前线程里“独立服务器模板仍有 nullable 警告”的记录已过期,至少现有生成工程与解决方案编译均已清零
- PowerShell 查看 UTF-8 中文时会出现乱码,但文件本身已按 UTF-8 写入
ShrinkNetwork.Integration.EventBus当前HasResult只回传:EventResultIsCanceledErrorCode / ErrorMessage
- 还不会自动回传事件对象其它字段的最终改动
- 当前生成器虽然已经把网络事件纳入一等公民,但生成结果仍以“可编译、可注册、可继续补业务”为目标,不会替你推断完整业务逻辑
- 当前默认安全基线已明显提高,但仍未覆盖 TLS、正式身份体系、协议版本协商、压测与故障演练
- 当前协议版本闸门与指标摘要已经具备最小生产辅助价值,但还没有 metrics 导出、trace、dashboard 或告警接入
Next Steps
- 在 Unity 编辑器中实际点击“生成完整独立服务器工程 / 刷新 Generated 合同”并补一轮运行时回归
- 继续补商业级缺口时,优先排:
- TLS / 安全信道
- 正式身份体系与令牌轮换
- 更细粒度的协议兼容协商,而不是当前这种“窗口校验 + 直接断开”
- metrics 导出 / trace / dashboard / 告警
- 压测、模糊包、断线与兼容回归
- 后续修改服务器生成器时保持语义扫描、命名空间同名拒绝和模板哈希预检测试。
- 如果要继续收口代码层细节,优先处理公开 API 中残留的 nullable 语义不一致,而不是重复消化已不存在的构建警告
- 如果后续彻底放弃旧心智,可把公开 API 中残留的
route = null一类签名继续做 nullable 收口
Last Update
-
2026-08-29: 完成第三方合规排查并新增根
THIRD-PARTY-NOTICES.md(README 已加"第三方与合规"入口)。结论:NeoForge / Minecraft Forge 与 MessagePipe 仅为概念参考(Docs/JustAnyProjectArchitectureAudit.mdA.3 有既有声明;EventBus 的五级优先级、receiveCanceled、EventResult{DEFAULT,ALLOW,DENY}、Attach(object)对应 Forge API 语义,实现为原创未复制代码,不触发 LGPL 衍生义务);MessagePipe 未引入依赖、API 形态不构成高度相似;AlicizaX(GitHub 组织)在代码、文档、git 历史中零引用,ShrinkInstaller子模块历史为自研。真正触发 MIT 归属义务的是Assets/Modules/ShrinkNetwork/Plugins/Kcp-CSharp.dll(Molth/Kcp-CSharp,上游 KCP)与System.Runtime.CompilerServices.Unsafe.dll,两者版权行与 MIT 全文已收录进声明文件;UniTask / MessagePack / Newtonsoft.Json 为外挂包依赖已登记。遗留:根仓库本身尚无 LICENSE(EventBus 模块已有 MIT),且ShrinkNetwork模块独立发布时需把 DLL 声明同步进该模块仓库。 -
2026-04-10: 已新增
Assets/Modules/ShrinkTutorial/独立包,落地一套可复用的互动式引导系统,包含ShrinkTutorialManager、ShrinkTutorialData / ShrinkTutorialStep / ShrinkTutorialDatabase、默认PlayerPrefs持久化、ShrinkTutorialAnchor / ShrinkTutorialTrigger、遮罩挖洞与提示框 UI、以及ShrinkSDK/引导/*/ShrinkSDK/Tutorial/*编辑器入口。 -
2026-04-10: 已新增示例场景
Assets/Scenes/ShrinkTutorialSample.unity,并配套生成Assets/Modules/ShrinkTutorial/Samples/Resources/ShrinkTutorialSettings.asset、Assets/Modules/ShrinkTutorial/Samples/ShrinkTutorialSampleDatabase.asset、Assets/Modules/ShrinkTutorial/Samples/ShrinkTutorialSampleTutorial.asset。示例流程覆盖三类核心路径:静态目标点击、运行时动态锚点等待、CompleteStep(customEventName)自定义事件完成。 -
2026-04-10: 示例场景入口脚本为
Assets/Modules/ShrinkTutorial/Runtime/Samples/ShrinkTutorialSampleSceneController.cs,一键重建入口为Assets/Modules/ShrinkTutorial/Editor/Samples/ShrinkTutorialSampleSceneBuilder.cs,菜单为ShrinkSDK/引导/创建示例场景与 ASCII 别名ShrinkSDK/Tutorial/Create Sample Scene。后续如果示例场景被手改或损坏,可直接走该菜单重建。 -
2026-04-10: 本轮已做命令行编译验证:
ShrinkTutorial.Runtime.csproj、ShrinkTutorial.Editor.csproj、ShrinkSDK.sln均为0 warning / 0 error。Unity 侧也完成了一轮示例场景 PlayMode 烟测,并修复了ShrinkTutorialDialog.Initialize()在已有RectTransform上重复AddComponent<RectTransform>()导致的运行时空引用。 -
2026-04-10: 当前示例场景文案已改为英文,不是产品方向选择,而是临时规避 TMP 默认字体缺少中文字形导致的方块/警告。若后续要把示例或引导系统默认文案恢复成中文,优先补一个可用的中文 TMP 字体资产,再统一改回中文,避免再次出现
LiberationSans SDF缺字警告。 -
2026-04-07: 已补上给外部模组开发者使用的
Mod SDK导出器。新入口是ShrinkSDK/Mod/导出 Mod SDK 开发包,会先构建ShrinkSDK.sln,再导出Libs/ + Templates/ExternalMod/SampleShrinkMod/ + README + manifest.json;其中外部模板已改成引用导出包里的 DLL,而不再直接引用本地仓库csproj。 -
2026-04-07: 因外部独立模组工程在用户 IDE 环境里仍会撞到
Microsoft.NET.SDK.WorkloadAutoImportPropsLocator解析问题,已追加一条更省事的“仓库内模组模板”路径。新入口是ShrinkSDK/Mod/生成仓库内模组模板(推荐),会直接生成到当前 Unity 项目的Assets下并复用现有ShrinkSDK.sln/ asmdef 编译链,作为当前更推荐的模组开发入口。 -
2026-04-07: 已给
ShrinkModFramework补上外部 DLL 模组模板生成器。新入口是ShrinkSDK/Mod/生成外部模组模板,实现位于Assets/Modules/ShrinkModFramework/Editor/Scaffolding/,会生成带csproj + build.ps1 + 示例模组代码 + README的独立模组工程,方便模组开发者直接构建 DLL 并投放到Mods目录。 -
2026-04-07: 已整理
Assets/Modules/ShrinkModFramework/Runtime/目录结构,把平铺脚本拆成Bootstrap / Core / Metadata / Registry / Loading / Network / Integration七层;同时同步更新Assets/Modules/ShrinkModFramework/README.md与.planning/codebase/STRUCTURE.md,把模组框架当前真实目录与推荐阅读顺序补齐。 -
2026-04-07: 用户已在实际环境中完成本轮回归,反馈当前
ShrinkCommand/ShrinkNetwork/ 独立服务器生成链路“测试过了没问题”。这意味着前面“还缺 Unity 编辑器内实际回归验证”的记录对当前这条链路已过期;当前可把状态视为:代码编译全绿,且已有用户侧真实验证通过。 -
2026-04-07: 已继续把
ShrinkCommand/ShrinkNetwork相关 nullable 收口做到当前全绿。先补齐Assets/Modules/ShrinkCommand.Integration.EventBus/与Assets/Modules/ShrinkCommand.Integration.Network/的#nullable enable,再把Assets/Modules/ShrinkNetwork/Runtime的消息元数据、权限、注册器、路由器、会话、服务、序列化器、EventBus 桥接等公共类型按真实可空语义收口;同时把GeneratedServers/ShrinkNetwork.ServerHost/Generated/UnityGeneratedNetworkContracts.g.cs里LanJoinRoomResponse.Players的数组默认值补齐,并把源头生成器Assets/Modules/ShrinkNetwork/Editor/Scaffolding/ShrinkDedicatedServerScaffoldGenerator.cs的GetDefaultInitializer(...)改成对任意T[]都自动生成Array.Empty<T>(),避免后续重新生成时 warning 回弹。已实际验证:dotnet build .\\ShrinkSDK.sln /m:1与dotnet build .\\GeneratedServers\\ShrinkNetwork.ServerHost\\ShrinkNetwork.ServerHost.csproj /nr:false现都为0 warning / 0 error。 -
2026-04-07: 已修复
ShrinkCommand在 Unity 侧的兼容性编译断点。Assets/Modules/ShrinkCommand/Runtime/Core/ShrinkCommandService.cs与Assets/Modules/ShrinkCommand/Runtime/Metadata/ShrinkCommandTypes.cs现已显式开启#nullable enable,并把依赖init的对象初始化属性改成 Unity 2022 当前编译链可稳定通过的set,避免再次触发System.Runtime.CompilerServices.IsExternalInit缺失;同时顺手收口了ShrinkCommandRegHelper.cs与ShrinkCommandService.cs内部的几处 nullable warning。已实际验证:dotnet build .\\ShrinkCommand.Runtime.csproj /m:1、dotnet build .\\GeneratedServers\\ShrinkCommand.RuntimeSmoke\\ShrinkCommand.RuntimeSmoke.csproj /nr:false均为0 warning / 0 error;dotnet build .\\ShrinkSDK.sln /m:1与dotnet build .\\GeneratedServers\\ShrinkNetwork.ServerHost\\ShrinkNetwork.ServerHost.csproj /nr:false也都恢复到0 error。当前残留 warning 已不在这两个修复点本体,而是在既有的ShrinkCommand.Integration.*与ShrinkNetworknullable 收口面。 -
2026-04-06: 已补宿主文本配置文件能力。新增
GeneratedServers/ShrinkNetwork.ServerHost/server.properties与模板server.properties.txt,风格对齐 Minecraft 的key=value配置;Program.cs启动改为先走ServerHostProperties.LoadOrCreate(),首次启动缺文件时自动落默认配置,并打印配置文件路径、是否首次生成、配置告警与最终优先级。当前规则为“代码默认值 < server.properties < 环境变量”;同时补了SHRINK_SERVER_CONFIG_PATH自定义配置文件路径入口,并把UnityAssetsPath/ScanOutputDirectory的默认解析从易错的AppContext.BaseDirectory相对跳转改成基于宿主工程目录定位。 -
2026-04-06: 已补上运行时烟测闭环。新增
GeneratedServers/ShrinkNetwork.RuntimeSmoke/轻量控制台烟测工具,直接覆盖“登录拿令牌 -> 鉴权后业务 RPC ->server/auth/refresh续期 -> 篡改令牌后被宿主断链”。同时把会话令牌关键配置补成环境变量:SHRINK_SERVER_ENABLE_SESSION_TOKENS / SHRINK_SERVER_SESSION_TOKEN_TTL_SECONDS / SHRINK_SERVER_SESSION_TOKEN_REFRESH_WINDOW_SECONDS / SHRINK_SERVER_DISCONNECT_ON_INVALID_SESSION_TOKEN。已实际跑通:宿主在SHRINK_SERVER_AUTH_TOKEN=smoke-token、TTL/续期窗口都为120秒时,烟测日志确认Login ok、Join room ok、Refresh ok、Tampered token rejected with disconnect、PASS;宿主日志也确认坏令牌请求被拒绝并主动踢线。 -
2026-04-06: 已补上“正式身份/会话令牌体系”第一版。
ShrinkNetworkPacket新增SessionToken与到期时间戳;ShrinkNetworkSession会自动持有并回传当前令牌;ShrinkNetworkService新增IncomingPacketValidator与AuthRejectedCount指标。独立宿主与模板侧新增server/auth/refresh,登录成功后签发内存态会话令牌,并按ServerHostOptions.EnableSessionTokens / SessionTokenTtlSeconds / SessionTokenRefreshWindowSeconds / DisconnectOnInvalidSessionToken做逐包校验与续期。已实际验证:dotnet build .\\Assembly-CSharp.csproj /m:1 -p:BaseIntermediateOutputPath=Temp\\CliObj\\Assembly-CSharp\\、dotnet build .\\GeneratedServers\\ShrinkNetwork.ServerHost\\ShrinkNetwork.ServerHost.csproj /nr:false、dotnet build .\\ShrinkSDK.sln /m:1全部通过;Unity 侧与解决方案侧恢复到0 warning / 0 error,宿主仍保留既有 nullable warnings;本轮尚未做真实登录-续期-断链运行时回归。 -
2026-04-06: 已补完 TCP TLS 第一版收口。
ShrinkTcpClientTransport/ShrinkTcpServerTransport与当前GeneratedServers、模板宿主都已接入可选ShrinkTcpTlsOptions,TCP 读包路径统一改为Stream以兼容SslStream。同时把ShrinkTcpTlsOptions的实际定义移到Runtime/Transport/Abstractions/IShrinkNetworkTransport.cs,原Runtime/Transport/Tcp/ShrinkTcpTlsOptions.cs仅保留占位,避免 Unity 尚未刷新工程文件时再次出现“文件已在磁盘上但类型不可见”的构建断点。 -
已补记商业级第二轮硬化:协议版本闸门、会话踢除接口、基础指标快照与宿主周期性摘要;Unity 侧命令行构建仍保持 0 warning / 0 error,独立服务器宿主仍存在既有 nullable warnings,下一续接点转向 TLS / 身份体系 / 真正的观测导出
-
2026-04-06: 宸茶ˉ涓?Minecraft 椋庢牸鐨勭嫭绔嬪懡浠ょ郴缁熶笌妗ユ帴灞傘€傛柊澧?
Assets/Modules/ShrinkCommand/鐙珛鍛戒护杩愯鏃讹紝鏀寔璺緞寮忓懡浠ゃ€佽礊蹇冨弬鏁般€佹潈闄愩€佹潵婧愬垽瀹氥€佸睘鎬佸紡鑷姩娉ㄥ唽锛涘悓鏃舵柊澧?Assets/Modules/ShrinkCommand.Integration.EventBus/涓?Assets/Modules/ShrinkCommand.Integration.Network/锛屽墠鑰呮敮鎸佺敤ShrinkCommandExecuteRequestEvent璇锋眰鎵ц鍛戒护骞跺彂甯?executing / executed / failed 浜嬩欢锛屽悗鑰呮敮鎸佺敤command/executeRPC 鎵ц杩滅▼鍛戒护銆傚綋鍓?GeneratedServers/ShrinkNetwork.ServerHost宸叉敼涓哄叡浜?ShrinkCommandService锛屾帶鍒跺彴涓庣綉缁滄ˉ鎺ュ叡鐢ㄥ悓涓€濂楀懡浠わ紱瀹夸富鍦?stdin EOF 鏃朵笉鍐嶇珛鍗抽€€鍑猴紝閫傞厤鍚庡彴杩涚▼鍚姩銆傚凡瀹為檯楠岃瘉锛?dotnet run --project .\\GeneratedServers\\ShrinkCommand.RuntimeSmoke\\ShrinkCommand.RuntimeSmoke.csprojPASS锛?dotnet run --project .\\GeneratedServers\\ShrinkCommand.EventBusSmoke\\ShrinkCommand.EventBusSmoke.csprojPASS锛屼互鍙婂悗鍙板惎鍔ㄥ涓?+dotnet run --project .\\GeneratedServers\\ShrinkNetwork.RuntimeSmoke\\ShrinkNetwork.RuntimeSmoke.csproj -- 127.0.0.1 17777 smoke-token runtime-smokePASS锛屽凡鐪熷疄瑕嗙洊鈥滅櫥褰?-> 涓氬姟 RPC -> 杩滅▼status鍛戒护 -> 绡℃敼浠ょ墝鏂摼鈥濄€?