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

3.3 KiB
Raw Blame History

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.