86 lines
2.1 KiB
ReStructuredText
86 lines
2.1 KiB
ReStructuredText
==============
|
|
visual effects
|
|
==============
|
|
|
|
the overlay system for transient visual effects like cloud trails.
|
|
|
|
overview
|
|
========
|
|
|
|
effects are temporary overlays displayed on top of terrain in the viewport.
|
|
each effect has a position, character, color, and expiration time. they're
|
|
rendered last-wins on overlap, cleaned up passively in the game loop.
|
|
|
|
data model
|
|
==========
|
|
|
|
effect dataclass
|
|
----------------
|
|
|
|
defined in ``effects.py``::
|
|
|
|
@dataclass
|
|
class Effect:
|
|
x: int
|
|
y: int
|
|
char: str
|
|
color: str # ANSI code
|
|
expires_at: float # monotonic time
|
|
|
|
global state
|
|
------------
|
|
|
|
single global list::
|
|
|
|
active_effects: list[Effect] = []
|
|
|
|
no per-zone partitioning. simple.
|
|
|
|
core functions
|
|
==============
|
|
|
|
``add_effect(x, y, char, color, ttl)``
|
|
creates effect with expiry at ``time.monotonic() + ttl``, appends to list
|
|
|
|
``get_effects_at(x, y)``
|
|
returns active effects at position, auto-filters expired ones
|
|
|
|
``clear_expired()``
|
|
in-place list mutation to drop expired effects. called once per tick
|
|
(10/sec) in ``server.py`` game loop
|
|
|
|
rendering
|
|
=========
|
|
|
|
in ``look.py``, for each viewport tile:
|
|
|
|
1. check ``get_effects_at(x, y)``
|
|
2. if effects exist, take ``effects[-1]`` (most recent)
|
|
3. display its ``char`` and ``color``, overlaying terrain
|
|
|
|
last-added effect wins on overlap.
|
|
|
|
timing
|
|
======
|
|
|
|
uses ``time.monotonic()`` for consistent async timing. ttl in seconds.
|
|
|
|
current usage: fly command creates cloud trail ("~" bright white) with
|
|
staggered ttls (1.5s base + 0.4s per step) so clouds fade origin to destination.
|
|
|
|
design decisions
|
|
================
|
|
|
|
- global state, not per-zone (simplicity)
|
|
- passive cleanup via tick-based ``clear_expired()``
|
|
- last-wins overlay (no z-index, no blending)
|
|
- just char + ANSI color (minimal rendering)
|
|
- monotonic time (no wall clock drift)
|
|
|
|
code
|
|
====
|
|
|
|
- ``src/mudlib/effects.py`` - dataclass, functions, global state
|
|
- ``src/mudlib/look.py`` - viewport rendering with effect overlay
|
|
- ``src/mudlib/server.py`` - game loop calls ``clear_expired()``
|
|
- ``content/commands/fly.toml`` - cloud trail effect usage
|