godot-theme-easter

概述

季节性「复活节化」工具包：明亮的粉彩色、活泼的动感和蛋/兔子图标——由日历和设置控制。

必须首先阅读： easter_seasonal_activation_gate.gd——日期范围、「Disable Seasonal Themes」退出选项（user://settings.cfg）和开发覆盖。设置更改时调用 refresh_activation()；切勿在 _process 中轮询日历。

前置条件： 在存在基础 Theme 资源之前，不要加载 godot-ui-theming——季节性叠加层会注入 StyleBox 覆盖，而不是取代基础 Theme 的编写工作。

季节性引导（按顺序）

1. 开关 — 附加 easter_seasonal_activation_gate.gd；在 _ready 和设置更改时调用 refresh_activation()。
2. 主题 — 若开关已启用：必须使用 easter_runtime_ui_themer.gd，并采用 easter_pastel_color_palette.gd 中的色彩令牌。
3. 音频 — 必须使用 easter_seasonal_audio_swapper.gd，将标准 UI 音效映射为季节性音频流。
4. 动感效果 — 仅在步骤 1–3 通过后，才叠加彩纸/闪光/光标/摇晃脚本（开关关闭时，完全跳过步骤 2–4）。

决策树——替代绘制器（任选其一）

场景	使用	不要同时接入
通过 surface_override 为 3D 网格添加季节性着色	easter_mesh_painter_override.gd	在同一网格上使用 easter_palette_override.gd
已接入 2D/modulate 或材质槽替换	easter_palette_override.gd 或 seasonal_material_swapper.gd	在同一目标上使用 mesh_painter

核心组件（专家级复活节工具）

easter_seasonal_activation_gate.gd

必须使用——支持日期判断、退出选项和开发覆盖的管理器。

easter_pastel_color_palette.gd

粉彩色 Color 令牌的唯一事实来源——不要在 SKILL 正文或零散脚本中硬编码十六进制色值列表。

easter_runtime_ui_themer.gd

运行时主题注入器，用于在整个 UI 树中批量应用粉彩样式。

easter_squash_stretch_juice.gd

使用 Tweens 实现的专家级「挤压与拉伸」逻辑，打造有机的蛋状交互效果。

easter_shimmer_vfx_emitter.gd

专业级「隐藏物品」闪光效果，带有加色混合和缩放曲线。

easter_egg_collection_tracker.gd

用于追踪隐藏物品的专家级注册表，通过信号实现进度通知。

easter_mesh_painter_override.gd

使用表面覆盖进行季节性 3D 材质替换，同时保留基础资源。

easter_wobble_physics_body.gd

由不稳定性驱动的物理实体，实现「蛋状」摇晃移动。

easter_camera_pop_juice.gd

沉浸式 FOV「冲击」逻辑，突出收集或弹出事件。

easter_confetti_canon_vfx.gd

庆祝用彩纸爆炸效果，包含多色粉彩碎片。

easter_custom_cursor_manager.gd

将系统鼠标光标替换为主题复活节图标的专家级逻辑。

easter_seasonal_audio_swapper.gd

动态音频资源加载器，用季节性变体替换标准 UI 音效。

easter_palette_override.gd / seasonal_material_swapper.gd

替代绘制器——请参阅上方的 决策树——替代绘制器；每个目标选择一条路径。

视觉指南

• 颜色： 从 easter_pastel_color_palette.gd 导入色彩标记（PINK、BLUE、YELLOW、MINT、PURPLE）——切勿在功能中随意罗列十六进制颜色值。
• 形状： 使用圆角（corner_radius > 8–12）。避免尖锐边缘和高对比度的黑色。
• VFX： 通过 confetti/shimmer 脚本添加彩纸、闪光和缎带效果。

切勿这样做（复活节专家规则）

美学与动感

• 切勿使用尖锐边缘或高对比度的黑色——复活节美学偏好圆角（corner_radius > 12）和柔和的粉彩色调。
• 切勿使用标准线性缩放来制作弹跳效果——线性缩放会显得“机械”。始终对有机彩蛋使用 TRANS_ELASTIC 或 TRANS_QUART。
• 切勿对复活节粒子使用面向摄像机的效果——在近距离 UI 或 VR 中，面向摄像机的闪光看起来很扁平。请使用基于网格的粒子或轴向旋转。

逻辑与性能

• 切勿修改原始 .mesh 或 .tres 资源——替换共享资源上的材质，会影响游戏中的每个实例。始终使用 surface_override 或 duplicate()。
• 切勿在 _process 中检查日期——每帧检查系统日历会造成浪费。请在 _ready 时或通过激活门控响应事件时调用一次 Time.get_date_dict_from_system()。
• 切勿忽略“非季节主题”切换项——有些玩家不喜欢季节性覆盖。请始终在设置中提供“停用季节主题”选项（通过门控的 ConfigFile 键连接）。

高级主题化钩子

• 动态 Z 顺序： 使用 RenderingServer.canvas_item_set_draw_index()，无需重新设置节点父级即可将已收集的彩蛋粒子动态移到 UI 堆栈前方。
• 物理插值： 对受物理驱动的彩蛋使用 TRANS_ELASTIC 补间时，调用 RenderingServer.canvas_item_reset_physics_interpolation()，避免弹跳动画首帧出现视觉“抖动”。
• StyleBox 覆盖： 使用 Control.add_theme_stylebox_override("panel", my_stylebox)，而不要修改全局 Theme，以将季节性更改限制在特定 UI 模块中。

复活节专家实现

1. 自定义鼠标光标（动感）

必须： easter_custom_cursor_manager.gd——始终设置 hotspot（兔耳尖端／底部）。

2. 主题音效加载器

必须： easter_seasonal_audio_swapper.gd——使用原始 AudioStream → 季节性 AudioStream 配对的资源映射。

3. 世界环境覆盖（春日辉光）

在过渡期间对 Environment 的环境光／色调映射／雾效进行补间——切勿在帧中途硬切颜色。

func _apply_spring_env(env: Environment) -> void:
    var tween := create_tween()
    tween.tween_property(env, "ambient_light_color", EasterPastelColorPalette.YELLOW, 2.0)
    tween.tween_property(env, "tonemap_exposure", 1.2, 2.0)
    tween.tween_property(env, "fog_light_color", EasterPastelColorPalette.BLUE, 2.0)

深入配方（按需查阅）

LLM 忽略规则：如果通用 Agent 在阅读前不会知道某项内容，就将其放在这里或 scripts/ 中——切勿删除，只能移动。

主题	参考资料
光标／音频／环境配方	seasonal-implementation-recipes.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作分派给相关领域时再加载相关技能——不要预加载整个技能网络。

官方文档

• GUI 换肤 — 季节主题切换与 StyleBox 隔离。
• 使用主题编辑器 — 无需仅通过代码制作皮肤，即可创建复活节主题变体。
• 主题类型变体 — 创建蛋类／按钮变体，无需派生整个主题。
• 粒子系统（2D） — 为可收集物增添活力的彩纸／闪光视觉特效。
• Tween — 弹性蛋弹跳与镜头冲击效果。
• 环境与后期处理 — 春日 WorldEnvironment 泛光／雾效补间。
• Theme — 运行时分配季节主题。
• Input — 自定义兔子光标热点。
• AudioStreamPlayer — 播放季节音效库。
• RenderingServer — 修复增添效果的蛋的绘制索引与物理插值问题。
• GPUParticles2D — 彩纸炮与闪光发射器。
• Environment — 环境光／色调映射／雾效的季节性覆盖设置。

相关技能

前置条件

• godot-ui-theming — 制作季节覆盖层前，先了解基础 Theme 架构。
• godot-project-foundations — 季节包的资源文件夹与启用门控。
• godot-resource-data-patterns — 音效覆盖映射与调色板 Resources。
• godot-signal-architecture — 收集追踪器与季节启用事件。

补充技能

• godot-tweening — 弹性 TRANS 弹跳与镜头表现力。
• godot-particles — 无需重新发明 GPUParticles，即可制作彩纸／闪光发射器。
• godot-audio-systems — 季节音效库与总线布线。
• godot-2d-animation — 为可收集物添加挤压／拉伸效果。
• godot-camera-systems — 收集蛋时的镜头冲击效果。
• godot-3d-lighting — 3D 游戏中的春日环境泛光效果。

下游／使用者

• godot-genre-party — 季节性派对模式经常会复用这套趣味系统。
• godot-genre-puzzle — 将收集彩蛋活动作为轻量谜题内容。
• godot-game-loop-collection — 消耗季节性追踪器的收集循环。
• godot-monte-carlo-balancer — 如果彩蛋奖励会影响进度门槛，请验证掉落经济系统。

主模块

• godot-master — 季节主题的库路由器和镜像模块入口。