Developer Overview

The Wudlands is an open source, contributor-driven dark fantasy adventure platform. At its core it is a story engine — a system that loads externally authored adventure addons and runs them as live, interactive sessions for players. The platform is designed to be extended by two distinct groups: story contributors who write the adventures, and software developers who build and maintain the engine, tooling, and infrastructure that makes those adventures run.

Connect with us and explore the project on our community platforms:

Main repo
The Wudlands App

News
FAQ channel

EVRLOOT
Porting repo

Call for Contributors

The Wudlands is built by the community, for the community. We're actively recruiting contributors across multiple disciplines to help bring this dark fantasy world to life. Whether you're a writer, artist, developer, or designer, there are roles that match your skills and passion.

Story Writers craft the adventures that drive the platform. Your narratives are the foundation of player experiences — branching storylines, rich dialogue, and dark fantasy atmospheres that immerse players in the Wudlands universe.

Image Generators & Visual Artists create the visual identity of every scene. From atmospheric character portraits to haunting environment artwork, your images bring the world to life and define the aesthetic of each adventure addon.

Creative Directors & Game Designers shape the overall experience. You define the visual style, pacing, tone, and design language that unites all adventures into a cohesive dark fantasy world. Your vision sets the standard for quality and immersion.

Backend & Engine Developers build and maintain the engine that powers the platform. You work on session management, addon validation, blockchain integration, player routing, and the infrastructure that keeps adventures running smoothly at scale.

Automation & Tools Developers write tools and scripts that convert raw story content into playable scene-based adventures. You bridge the gap between narrative and engine, building the pipelines that allow non-technical contributors to publish their work.

Frontend & UI/UX Developers design and implement the player-facing interface. You work on scene rendering, choice presentation, wallet integration, and the smooth interactions that players encounter during every adventure.

Audio Designers & Composers add sonic depth to the experience. Sound effects, ambient music, and voice assets transform adventures from silent text into immersive multisensory journeys.

Community & Content Managers foster collaboration and quality. You review submissions, provide feedback to contributors, moderate community discussions, and ensure the addon ecosystem stays vibrant and on-brand.

1. For Story Contributors

If you want to contribute an adventure addon — a self-contained story with scenes, choices, images, and branching paths — you do not need to write any code. Adventures are defined in a structured JSON format and submitted alongside image assets. The engine handles everything else: loading, validation, session management, rendering, and player routing.

Everything you need to know about the addon format, image specifications, style presets, scene structure, dependencies, and submission requirements is documented in the Storyteller section. Start there.

This section is for the people building the platform itself.

2. For Software Developers

The Wudlands platform is built on a Next.js frontend and a FastAPI backend. The frontend handles rendering, player interaction, wallet integration, and the display of scene content. The backend is responsible for session state, addon loading, player routing, play count tracking, and revenue share logic. Both layers are designed to run multiple player sessions concurrently without interference — each session is isolated, stateful, and independently routed through its addon's scene graph.

The Addon Engine

The core of the platform is the addon engine — the system that takes a contributor's JSON file and turns it into a live, interactive session. When a player enters an adventure, the engine loads the addon definition for that adventure, validates its structure against the platform schema, and initialises a session record tied to that player and that addon. From that point forward, every choice the player makes is a traversal instruction: move from the current scene id to the target scene id specified by the selected choice.

The scene graph is an addressable map of scene objects keyed by id. The engine looks up the requested scene id in that map on every player action. The adventure starts at thedefault_entry, which serves as the normal session starting point. If the scene exists, it is returned and rendered. If it does not exist — because of a broken link in the addon, a missing node, or any other fault — the engine does not error or crash the session. Instead it falls back to the addon's emergency_exit scene, a dedicated error-recovery scene required by schema to exist and to lead the player toward the addon's escape_route. The session remains intact, the player can exit gracefully, and the fault is logged server-side for the addon author to review.

Parallel Sessions

The engine is stateless at the request level. Each player action arrives as an independent HTTP request carrying the player's session token, the addon id, and the target scene id. The backend resolves the session, validates the transition, and returns the next scene. No shared in-memory state is held between requests. This means any number of players can be running through the same addon — or different addons — simultaneously, with no coordination overhead between their sessions. Horizontal scaling is straightforward: additional backend instances can be added without any session affinity requirement, as long as session state is stored in a shared persistence layer.

Play counts are tracked per player per addon. When a player enters an adventure, the engine checks their remaining play count for that addon. If the count is zero, entry is refused until the player resets by paying the entry fee again. Play count decrements happen at session start, not at session end — a session that is abandoned mid-adventure still consumes a play. This mirrors the real-world model of paying for the seat, not the outcome.

Addon Loading & Validation

Addons are loaded from storage on session initialisation and cached for the duration of active sessions using that addon. The engine validates every loaded addon against the platform schema before making it available to players. Validation checks include: presence of all required fields, existence of the default_entry, emergency_exit, and escape_route scenes within the scene map, validity of all to targets in choice arrays, and correct boolean typing on ending flags. Addons that fail validation are not published. Addons that were published and subsequently become invalid due to a platform schema update are flagged for review and removed from active rotation until corrected.

Adventure Dependencies & Unlocks

Each addon may declare a list of prerequisite addon ids in its requires field and a list of addon ids it unlocks in its unlocks field. The engine resolves these at the player level: before a player can enter an addon, the backend checks whether all entries in that addon's requires list appear in the player's completed adventure record. If they do not, the adventure is displayed as locked with the missing prerequisites listed. When a player completes an adventure, the engine marks it in their record and evaluates the unlocks list, making newly accessible adventures available immediately.

Blockchain & Revenue Share

The platform operates on a blockchain environment, currently targeting Polkadot with an optional Ethereum fallback address per contributor. When a player pays the entry fee for an adventure, the revenue split is applied at transaction time: 80% is routed to the wallet address declared in the addon's eth_address field, and 20% is retained by the platform. If no wallet address is declared, the full amount is held by the platform until the contributor registers one. All contributor addresses and payout records are stored in a migration-safe format to support a potential future chain migration.

Image Rendering & Style Presets

Each scene may reference a single image by filename. At runtime, the frontend loads the image from the addon's asset directory and applies the CSS filter and transform defined by the scene's image_style preset. Presets are resolved client-side from a static lookup table — no server involvement is needed for filter application. Animated presets use CSS keyframe animations applied as class names. Overlay presets use positioned ::after pseudo-elements on the image wrapper. All presets are documented and previewed in the Story Contributor guidelines.