Files
sor/effect-plan.md
2026-07-02 13:09:05 -04:00

137 lines
3.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Implementation notes for repentance placeholder VFX.
Server Work
Add a visual-only broadcast when a Repentance successfully resolves.
Relevant files:
GameEngine.cs (line 260)
GamePlayCardHandler.cs (line 12)
GameMessages.cs (line 258)
AbilityDefinition.cs (line 125)
AbilityAnimationDefinition.cs (line 34)
Needed server pieces:
Add a new push DTO, for example RepentancePlaceholderVisualPush.
Payload should include:
eventId
sessionId
actorAccountId
sourceArchSpiritInstanceId
cardInstanceId
cardDefinitionId
cardName
affinity
targets
hasCustomAnimation
Detect successful Repentance resolution in game.play_card.
After GameEngine.PlayCard(...) succeeds and before/after state push, check:
card type was Repentance
card ability has no animation metadata, or animation metadata has no usable AssetUrl
Broadcast a visual-only push to all viewers.
Message type could be:
game.visual.repentance_placeholder
Send to:
acting player
opponent/all game players
spectators
Do not store this in GameState.
This is not gameplay state. It should be transient, like a sound or animation cue.
Target payload should reuse the same AbilityTarget shape where possible.
That keeps the client able to resolve:
unit target
tile target
player target fallback
targetless fallback
Client Work
Listen for the visual push and play a placeholder projectile from the acting player’s ArchSpirit to the target.
Relevant files:
Game.gd (line 796)
game_screen.gd (line 384)
game_screen.gd (line 1006)
board_controller.gd (line 321)
game_constants.gd (line 5)
Needed client pieces:
Add a signal in Game.gd.
Example:
signal repentance_placeholder_visual(payload: Dictionary)
Handle the new push message in Game.gd.
In the push router, add:
"game.visual.repentance_placeholder":
repentance_placeholder_visual.emit(payload as Dictionary)
Connect the signal in game_screen.gd.
The game screen should route the event to a dedicated VFX helper, not absorb a large amount of new effect code directly.
Add a focused VFX component.
Suggested path:
Client/origin-client/scenes/game/components/effects/repentance_placeholder_fx.gd
Responsibilities:
resolve ArchSpirit source world position
resolve target world position
spawn projectile
tween projectile to target
spawn impact particles
clean itself up
Color rules.
Use:
player/team color from state.teamColors
repentance affinity color from GameConstants.AFFINITY_COLORS
Suggested visual split:
projectile core: affinity color
trail/sparks: player color
impact ring: mix of both
Target resolution rules.
Resolve in this order:
target unit instance id to its current board position
target tile coordinate
target player ArchSpirit position
fallback to source ArchSpirit position
Animation timing.
Suggested defaults:
projectile duration: 0.35s to 0.8s, based on distance
impact duration: 0.5s to 0.8s
cleanup after around 1.2s
Future ability animation compatibility.
The client should ignore the placeholder if the server says hasCustomAnimation == true.
Later, active ability VFX can reuse the same visual event pattern with a broader message like:
game.visual.ability
Recommended Order
Add server DTO and push message.
Emit the push from successful Repentance channeling.
Add Game.gd signal and push routing.
Add placeholder VFX component.
Wire game_screen.gd to invoke it.
Test actor, opponent, and spectator views.