Building My Second Foundry VTT Module: Maleficar Manoeuvres

After finishing my first Foundry VTT module, I felt like I had a much better grasp of how Foundry works under the hood—and a clearer sense of what I wish I'd done differently the first time. So, I’ve started working on a second project: Maleficar Manoeuvres, a module aimed at improving token movement and tactical gameplay in Foundry VTT v13.

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!