But how do I hook into Foundry’s event system, check permissions, and still keep my code clean and loosely coupled?

FoundryHookAdapter (Infrastructure Layer)

Detects raw Foundry events and converts them to domain events. By hiding Foundry specifics here, the rest of the app remains blissfully ignorant of Foundry’s peculiarities.

// When a token is updated in Foundry:
handleTokenUpdate() {
  // Captures the update from Foundry's updateToken hook
  // Creates a TokenUpdateEvent with rotation data
  eventBus.emit('token:update', {
    tokenId: document.id,
    currentState: { rotation: 45, x: 100, y: 100, ... },
    changedState: { rotation: 90 },  // New rotation
    userId: 'abc123'
  });
}

TokenRotationCoordinator (Application Layer)

Listens for token updates and coordinates overlay rendering when rotation changes.

1. Detect rotation change

2. Fetch overlay types that respond to token rotation

3. Check who’s allowed to see them

4. Build a render context (dimensions, angles, positions)

5. Fire off render requests

// Subscribed to 'token:update' events
handleTokenUpdate(event: TokenUpdateEvent) {
  // Check if rotation changed
  if (event.changedState.rotation !== undefined) {
    // Get overlays that respond to rotation (like facing-arc)
    const rotationOverlays = overlayRegistry.getTypesForEvent('tokenRotate');

    // Check permissions - can this user see overlays on this token?
    const viewableOverlays = await permissionCoordinator.getViewableOverlaysForToken();

    // Build render context with rotation data
    const context: OverlayRenderContext = {
      rotation: {
        currentRotation: 45,
        newRotation: 90,
        tokenXCoordinate: 100,
        tokenYCoordinate: 100,
        tokenWidth: 50,
        tokenHeight: 50
      }
    };

OverlayRenderingService (Presentation Layer)

Manages the PixiJS graphics containers and coordinates rendering.

• Retrieves the overlay definition (FacingArcDefinition)

• Instantiates—or reuses—a PIXI.Graphics object

• Positions it at the token’s centre

• Hands off drawing to the renderer

renderTokenOverlay(overlayTypeId: 'facing-arc', tokenId: string, context: OverlayRenderContext) {
  // Get the overlay definition from registry
  const overlayDef = overlayRegistry.get('facing-arc'); // Returns FacingArcDefinition

  // Get the renderer from the definition
  const renderer = overlayDef.getRenderer(); // Returns FacingArcRenderer instance

  // Get or create PIXI graphics object for this token+overlay
  const graphics = getOrCreateGraphicsInstance(`${tokenId}-facing-arc`);

  // Position graphics at token centre
  const centerX = context.rotation.tokenXCoordinate + context.rotation.tokenWidth / 2;
  const centerY = context.rotation.tokenYCoordinate + context.rotation.tokenHeight / 2;
  graphics.position.set(centerX, centerY);

  // Delegate actual drawing to the renderer
  renderer.render(graphics, context);
}

FacingArcDefinition (Infrastructure Layer)

Defines the facing arc overlay configuration.

export const FacingArcDefinition: OverlayDefinition = {
  id: 'facing-arc',
  renderTriggers: ['tokenRotate', 'tokenMove'],
};

Because it lives in a registry, adding new overlays later (boundary, aura, custom shapes…) is just a matter of dropping in another definition.

FacingArcRenderer (Presentation Layer)

Actually draws the facing arc using PixiJS.

render(graphics: PIXI.Graphics, context: OverlayRenderContext) {
  // Clear previous drawing
  graphics.clear();

  // Get rotation from context
  const rotation = context.rotation?.currentRotation ?? 0;
  const radius = Math.max(context.rotation.tokenWidth, context.rotation.tokenHeight) / 2;

  // Calculate arc angles (20 degree arc)
  const arcAngle = 20 * Math.PI / 180;
  const facingAngle = ((rotation - 90) * (Math.PI / 180));
  const startAngle = facingAngle - arcAngle / 2;
  const endAngle = facingAngle + arcAngle / 2;

  // Draw the arc line
  graphics.lineStyle({
    width: 8,
    color: 0x8A6A1C,
    alpha: 0.8,
    cap: PIXI.LINE_CAP.ROUND
  });

  graphics.arc(0, 0, radius, startAngle, endAngle, false);
}

Complete Flow Sequence

1. User rotates token in Foundry UI

2. Foundry fires updateToken hook

3. FoundryHookAdapter catches hook, emits 'token:update' event

4. TokenRotationCoordinator receives event, checks if rotation changed

5. Coordinator queries OverlayRegistry for overlays with 'tokenRotate' trigger

6. Coordinator checks permissions via OverlayPermissionCoordinator

7. Coordinator builds render context with rotation data

8. Coordinator calls overlayRenderingService.renderTokenOverlay()

9. OverlayRenderingService gets FacingArcDefinition from registry

10. Service calls definition.getRenderer() to get FacingArcRenderer

11. Service creates/positions PIXI Graphics object

12. Service calls renderer.render(graphics, context)

13. FacingArcRenderer draws the arc at the new rotation angle

14. Facing arc appears on screen at token’s new rotation

Key Design Patterns

• Event-Driven: Loose coupling via an EventBus

• Clean Architecture: Clear separation between infrastructure, application, and presentation layers

• Strategy Pattern: Different renderers implement a common interface for each overlay type

• Registry Pattern: Dynamic registration and lookup of overlay definitions

• Permission System: Fine-grained control over who can see each overlay

This modular architecture makes it trivial to extend—simply drop in a new overlay definition and renderer, and the core flow remains untouched. Happy coding!

It bridges Foundry VTT’s infrastructure with my domain logic, keeping permissions clean, isolated, and easy to reason about.

Here’s a breakdown of how the whole thing works.

Entry Points: Where the Flow Begins

Overlay view permission checks kick off in a few key methods:

graph TD
    A[UI/Rendering System] --> B{Which Method?}
    B --> C[canViewOverlayOnToken - Single Check]
    B --> D[canViewOverlaysOnToken - Batch Check]
    B --> E[getViewableOverlaysForToken - Get All Viewable]

Single Overlay Check: canViewOverlayOnToken

This is the core function that checks one overlay on one token. Here's what it does under the hood:

// Check if a single overlay is viewable by the user
canViewOverlayOnToken(
    overlayId: string,
    targetToken: Token,
    userId: string,
    isGM: boolean,
    viewerTokens: Token[] = []
): boolean {
    const config = this.registry.get(overlayId);

    if (!config) {
        this.logger.warn(`Overlay "${overlayId}" isn’t registered.`);
        return false;
    }

    // Quick exit if the overlay doesn't require permission checks
    if (!config.usePermissionSystem) {
        return true;
    }

    // Gather the necessary data for a proper check
    const targetData = this.getCachedTokenData(targetToken);
    const viewerData = this.getCachedTokensData(viewerTokens);
    const allVisibleTokens = this.getAllVisibleTokensData();

    // Let the domain service handle the actual decision
    return this.permissionService.canViewOverlaysOnToken(
        targetData,
        userId,
        isGM,
        viewerData,
        allVisibleTokens
    );
}

Step-by-step:

1. Registry Lookup

   • Pulls the overlay config from the registry

   • If not found, returns false

2. Fast Path Check

   • If usePermissionSystem === false, returns true immediately

   • This skips heavy logic for overlays that don’t need it

3. Data Conversion (Cached)

   • Converts targetToken and viewerTokens[] into TokenSightData

   • Fetches all visible tokens if needed

4. Domain Permission Check

   • Calls permissionService.canViewOverlays()

   • This service lives in the pure domain layer—no Foundry types involved

5. Return Result

   • Comes back with a boolean based on the domain logic

Caching Strategy: Keep It Fast, Keep It Simple

To avoid re-converting tokens constantly, I’ve built a lightweight caching layer:

// Token Data Cache Flow
    ┌─────────────────┐
    │  Foundry Token  │
    └────────┬────────┘
             ↓
┌────────────────────────┐
│   Generate Cache Key   │ → `${token.id}-${cacheGeneration}`
└────────────┬───────────┘
             ↓
        ┌────┴────┐
        │ Cached? │
        └────┬────┘
             ↓
         No ─┴── Yes
         ↓        ↓
      Convert    Return
      & Store    Cached

The key includes a generation number so I can invalidate it whenever needed (e.g. when tokens move or vision updates).

Example Flow: Full Walkthrough

Let’s say a user hovers over a token. I want to know which overlays are visible to them:

getViewableOverlaysForToken(token, userId, isGM, viewerTokens)

Behind the scenes:

1. Grab all overlays from the registry:
   ['movement-path', 'elevation-indicator', 'status-effects']

2. Call the batch check:
   canViewOverlaysOnToken([...], token, userId, isGM, viewerTokens)

3. For each overlay:

   • movement-path: needs permission → check domain

   • elevation-indicator: doesn’t need permission → allow

   • status-effects: needs permission → check domain

4. Result:
   ['elevation-indicator', 'status-effects']
   (assuming movement-path was denied)

Why This Works for Me

This setup gives me:

• Separation of concerns
  Foundry stays out of my domain logic. My domain doesn’t even know Foundry exists.

• Performance
  The system avoids unnecessary work and reuses data wherever possible.

• Flexibility
  I can add new permission types or overlay rules without touching Foundry code.

• Testability
  Domain services are testable in isolation, no mocks needed.

• Maintainability
  All Foundry-specific stuff lives in one place—the coordinator.

If you’re wrangling overlays in a similar way or building on Foundry and trying to decouple things, I think this structure makes it much easier to reason about and test.

Overlay Visibility – Requirements

For Players

As a player, I only want overlays to show up when they make sense—meaning, I should only see an overlay if my character would be able to see the token it’s attached to. This helps preserve immersion and makes decision-making more intuitive.

If I have a token selected, I want its overlays to show—of course. But for overlays on other tokens, I only want to see them if:

• The other token is visible on the canvas

• It’s not hidden in the scene configuration

• It lies within the selected token’s vision polygon

• There are no walls or barriers blocking line of sight

When no token is selected, I want the system to fall back on visibility from all tokens I control—so overlays still show accurately based on what my characters could see collectively.

For GMs

As a GM, it’s a different story. I want to see everything—all overlays, all the time. Full visibility means I can keep an eye on the battlefield, check for inconsistencies, and help players when needed.

Domain Layer – My Approach

Now, to support this behaviour in code, I’ve been thinking carefully about how to model the domain. Here’s how I’ve structured things.

I use four main layers in my domain model:

1. Entities – Mutable objects with identity

2. Value Objects – Immutable domain concepts

3. Interfaces – Contracts for infrastructure and external services

4. Types – Lightweight, structural definitions (like enums, DTOs, configs)

Entities – Things That Change and Persist

Entities are objects that have a unique ID and mutable state. For example:

export class MoveableToken {
    constructor(
        public readonly id: string,
        private position: Vector2,
        private rotation: number,
        private collisionShape: CollisionShape
    ) {}

    move(newPosition: Vector2): void {
        this.position = newPosition;
    }

    rotate(newRotation: number): void {
        this.rotation = newRotation;
    }
}

What makes this an entity:

• It has identity (id)

• Its state can change (position, rotation)

• I consider two entities the same if they share the same ID—not necessarily the same data

Value Objects – Immutable by Design

Value objects are all about immutability and equality by value:

export class Vector2 {
    constructor(
        public readonly x: number,
        public readonly y: number
    ) {}

    add(other: Vector2): Vector2 {
        return new Vector2(this.x + other.x, this.y + other.y);
    }

    equals(other: Vector2): boolean {
        return this.x === other.x && this.y === other.y;
    }
}

I reach for value objects when I want:

• Domain expressiveness

• Predictability

• Thread safety

• Easy equality comparison

Interfaces – Contracts for Flexibility

Interfaces help me define what needs to be done, not how.

export interface LineOfSightChecker {
    isBlocked(origin: Vector2, destination: Vector2): boolean;
}

export interface TokenOwnershipProvider {
    getOwnedTokenIds(userId: string): string[];
}

This makes it easy for me to swap implementations, mock them during tests, or inject platform-specific logic without tying it to my domain.

Types – Pure Data

I use types and enums to represent pure data without behaviour:

export enum GridType {
    Gridless = 0,
    Square = 1,
    Hex = 2
}

export interface SceneConfig {
    gridType: GridType;
    gridSize: number;
    useElevation: boolean;
    sceneCeiling: number;
    enable3DPathfinding: boolean;
    maxStepHeight: number;
}

Types are lightweight and ideal for:

• Configs

• DTOs

• Enums and constraints

• Representing shape without logic

Choosing the Right Tool for the Job

Purpose

Why This Structure Works for Me

This approach keeps my codebase:

• Testable – Logic lives in pure functions and classes

• Modular – Interfaces separate infrastructure from domain

• Extensible – Easy to extend or replace parts of the system

• Readable – Clear boundaries make it easier to reason about

By thinking in terms of entities, value objects, interfaces, and types, I avoid the dreaded "everything is just a class" pitfall. It also helps me align gameplay logic (like overlay visibility) with clean architectural decisions.

I think this is a strong foundation for building features that are both fun to use and maintainable to develop. If you’ve got similar patterns—or different ones—I’d love to hear about them.

This time around, I’m trying to push a little further, experiment a bit more, and apply some structure to how I approach things.

The Goal: Assisted Movement

Maleficar Manoeuvres is about making movement during combat smoother and more helpful for players and GMs. The idea is to provide:

• Pathfinding to show efficient routes,

• Collision detection so players can’t accidentally (or intentionally) walk through walls and other tokens,

• Visual aids like boundaries, facing, movement ranges, and potential hazards.

I want the experience to feel intuitive and responsive, without dragging down performance.

Tech Stack

I’m using a fairly modern stack that suits Foundry’s latest version. I’ve leaned toward tools I am unfamiliar with and want to understand better:

• Foundry VTT v13 – Using the latest API. No backwards compatibility (by design).

• TypeScript

• Svelte

• PixiJS v7 – Which Foundry uses internally, so it’s part of the deal.

• Vite

Architecture: Trying to Do Things Properly

With this module, I wanted to be more intentional about structure and scalability. My first module worked, but the code got messy fast. This time I’m following ideas from Clean Architecture and Domain-Driven Design—nothing super strict, but enough to separate concerns and avoid tangling everything together.

Project Structure

src/
├── application/       # Coordinates flow and higher-level logic
│   ├── commands/      # Handle specific actions or requests
│   └── factories/     # Dependency injection helpers
├── domain/            # Core game logic, rules, and decisions
│   ├── entities/      # Concepts like Token, Grid, MovementPlan
│   ├── services/      # Calculations and validations
│   └── value-objects/ # Immutable helpers like Position or Range
├── infrastructure/    # Hooks into Foundry and external systems
│   ├── adapters/      # Foundry-specific wrappers
│   └── events/        # Internal event system
├── presentation/      # User interface
│   ├── components/    # Svelte-based UI widgets
│   └── styles/        # CSS and visual polish
└── lib/               # Reusable utilities and helpers

Data Flow: Hook to UI

Most of the system is event-driven. Rather than having each part of the app call another directly, I’ve set up an EventBus so communication stays clean and loosely coupled. Here’s how data generally moves:

1. Foundry Hooks → Adapter
   Foundry triggers a hook (e.g. token movement), and the FoundryHookAdapter catches it.

2. Adapter → EventBus
   The adapter fires an internal event, so the rest of the app doesn’t need to know anything about Foundry-specific details.

3. EventBus → Commands and Services
   Commands take action based on events, often calling services that implement game logic.

4. Domain Logic → State Update
   Services in the domain layer decide what should happen (e.g., “This path is invalid”), and update the state accordingly.

5. State → UI
   Components listen for state changes and update the interface.

Why This Structure?

• It’s easier to test – Domain logic is separate from the UI and Foundry, so I can write unit tests without launching the game.

• It’s easier to change things – Since each layer has a clear purpose, I’m not afraid of breaking everything when I tweak something.

• It’s easier to think about – I spend less time wondering where to put new code.

I’m not saying this is the “perfect” architecture for every Foundry module—but for something with a bit of complexity, I hope it will help.

Still Early Days

The project is still in its early stages, and I’m learning a lot as I go. There’s plenty left to figure out, and I’m sure I’ll make mistakes. But so far, I’m excited by how it’s shaping up.

If you’re working on something similar, or you’ve tackled movement or pathfinding in Foundry before, I’d love to hear from you. Suggestions, warnings, or even “I tried that and it blew up”—it’s all helpful.

Thanks for reading!

You can check it out on GitHub: Health Arc.

I’ve been thinking for a while about starting a space where I can share small, playful coding projects inspired by the games I love—and invite you along to build and experiment with me. Whether you’re curious about creating a simple dungeon generator, scripting an AI opponent, or just learning how to blend code and creativity, this blog will be our testing ground.

The idea is to keep things light and approachable. I’ll post short tutorials, quick challenges, and bite-sized examples that you can follow in an hour or two. No grand, daunting frameworks—just fun snippets and experiments that spark new ideas and help you practise coding in a gaming context.

Best of all, I want this to be a collaborative lab. Share your tweaks and variations, suggest new experiment ideas, or show off the tiny project you just finished. I’ll highlight interesting community contributions and share feedback so we’re all learning together.

Stay tuned for our first coding quest—coming soon! Feel free to comment below with project ideas or questions, and let’s see what we can build, one small step at a time.