Introduction

Develop a detailed design document for Hellsword, a dark fantasy collectible card game (CCG) set in a voxel sandbox universe. The game is hosted on a Linux server using PHP and runs as part of a ConcreteCMS v9 website—leveraging its built‐in user authentication, content management, and modular customization. Hellsword features a tile-based board where each tile represents a unique 3D sandbox world. Players build decks (up to 15 cards per deck, with no copy limits and support for multiple decks) that include a customizable craftable commander card, and use these decks in strategic, turn-based card battles. Cards in Hellsword are versatile data bundles (encoded in JSON or XML) that encapsulate combat, crafting, and world‐placement functions. In addition, players can spawn events on their voxel worlds, sending public or invite‐only invites for cooperative battles against event monsters. A robust notification system supports in-game alerts, social sharing, email, and SMS—with granular user controls.

 

1. Game Vision and Context

1.1 Core Concept

• Genre:
  Dark Fantasy CCG + Voxel Sandbox

• Setting:
  A grimdark universe where rival factions (Necrotech, Abyssal, Draconic, Eldritch) battle for territorial and strategic supremacy.

• Gameplay Innovations:

  • Versatile Card System: Every block, item, and entity is represented as a card—a dynamic data bundle that can participate in combat, be placed in the voxel world, or serve in crafting.

  • Deck Building: Players build decks of up to 15 cards (including one craftable commander card) and can maintain multiple decks to suit different strategies (PvP, guild battles, events).

  • Commander Cards: Special cards that players can craft and customize to reflect their likeness, enhanced by commands earned through missions.

  • Player-Spawned Events: In-voxel worlds, players can trigger events that send out invitations (public or invite-only) to other players for cooperative battles against event-specific monsters.

  • Circular Faction Logic: A rock-paper-scissors dynamic among factions (e.g., Necrotech > Abyssal > Draconic > Eldritch > Necrotech) that influences combat outcomes and card synergies.

• Technical Environment:
  Hosted on a Linux server with PHP, integrated within ConcreteCMS v9 for streamlined user management, content delivery, and modular expansion.

1.2 Community and Social Integration

• User Management:
  Utilize ConcreteCMS’s registration and login services.

• Social Features:
  In-game real-time chat, leaderboards, forums, and voice/video integration.

• Notifications:
  Granular notification controls that let players choose how they receive game alerts—in-game popups, social media integration, email (via SendGrid), and SMS (via Twilio).

 

2. Card System: Data Structure and Versatility

2.1 Card as a Comprehensive Data Bundle

In Hellsword, each card is a self-contained, multi-purpose entity defined by a JSON or XML data bundle. This bundle encapsulates every piece of information, asset reference, and code snippet required to define the card’s behavior, appearance, and functionality. Key aspects include:

• Combat, World-Building, and Crafting Data:
  Standard attributes such as attack, health, cost, 3D model paths, and flags for placement, crafting, or conversion.

• Dynamic Custom Attributes:
  A flexible container for additional attributes (e.g., energy regeneration, stealth bonus, area effect radius) that can be added or modified as needed.

• Inheritable Traits:
  Attributes flagged as inheritable will be passed on and cumulatively stack when a card is used as a component in minting a new card. This ensures that enhancements or buffs contributed by component cards carry forward.

• Schematic as Code Repository:
  The schematic attribute is pivotal—it contains a rich set of code (or references to code modules) that defines instructions and routines for the card.

  • Embedded Instructions: Any of the card’s attributes or its action routines may reference the schematic code to determine behavior.

  • Inheritance of Schematic: When a card is used in crafting or minting, its schematic (including all associated code) is inherited by the newly minted card, ensuring that complex behaviors are preserved.

• Action Routines Tied to Schematic:
  The action attribute no longer stands alone; it references the schematic for detailed instructions. For example, rather than simply specifying summonUnit, the action will invoke a function defined within the schematic code. This provides a dynamic way to adjust behaviors without changing the core data structure.

2.2 Example Data Structures

JSON Example (Single Card)

{
  "id": "1001",
  "name": "Necrotech Soldier",
  "picture": "necrotech_soldier.jpg",
  "model": "necrotech_soldier.obj",
  "schematic": {
    "code": "function executeAction(params){ /* complex summon logic here */ }",
    "version": "v2",
    "inheritance": true
  },
  "attack": 2,
  "health": 6,
  "cost": 1,
  "type": "Unit",
  "faction": "Necrotech",
  "skills": [
    {"id": "armored", "x": 2}
  ],
  "placeable": false,
  "craftable": false,
  "convertible": true,
  "salvageable": true,
  "customAttributes": {
    "energyRegen": 0,
    "invisibility": false
  },
  "inheritableTraits": {
    "buff": 0.0
  },
  "action": {
    "version": "v2",
    "function": "executeAction",
    "parameters": {
      "unitType": "necrotech_soldier",
      "position": "battlefield"
    },
    "referenceSchematic": true
  }
}

XML Example (Single Card)

<card>
  <id>1001</id>
  <name>Necrotech Soldier</name>
  <picture>necrotech_soldier.jpg</picture>
  <model>necrotech_soldier.obj</model>
  <schematic version="v2" inheritance="true">
    <code><![CDATA[
      function executeAction(params){
        // complex summon logic here
      }
    ]]></code>
  </schematic>
  <attack>2</attack>
  <health>6</health>
  <cost>1</cost>
  <type>Unit</type>
  <faction>Necrotech</faction>
  <skills>
    <skill id="armored" x="2"/>
  </skills>
  <placeable>false</placeable>
  <craftable>false</craftable>
  <convertible>true</convertible>
  <salvageable>true</salvageable>
  <customAttributes>
    <energyRegen>0</energyRegen>
    <invisibility>false</invisibility>
  </customAttributes>
  <inheritableTraits>
    <buff>0.0</buff>
  </inheritableTraits>
  <action version="v2" referenceSchematic="true">
    <function>executeAction</function>
    <parameters>
      <unitType>necrotech_soldier</unitType>
      <position>battlefield</position>
    </parameters>
  </action>
</card>

2.3 Key Attributes Explained

• id: Unique identifier for the card.

• name, picture, model, schematic:

  • Schematic: Contains embedded code/instructions that define complex behaviors. The code is versioned and may be inherited by minted cards.

• attack, health, cost: Core combat statistics.

• type: Categorizes the card (Unit, Spell, Structure, Resource, Commander, etc.).

• faction: Indicates affiliation (Necrotech, Abyssal, Draconic, Eldritch, Neutral).

• skills: An array of abilities (e.g., "armored:2", "heal:5").

• Flags (placeable, craftable, convertible, salvageable): Define the card’s permitted interactions.

• customAttributes: A flexible section for additional, dynamically added properties.

• inheritableTraits: Attributes that, when flagged, are passed along during minting and may cumulatively stack.

• action:

  • References a function (typically defined in the schematic) to execute the card’s primary behavior.

  • Contains parameters and a flag (e.g., referenceSchematic: true) to indicate that it should consult the schematic for execution details.

 

3. Deck Structure and Composition

3.1 Deck Rules and Configuration

• Deck Size:
  Each deck can contain up to 15 cards.

• Multiple Decks:
  Players can create and manage multiple decks to suit different strategies or gameplay modes.

• Commander Card:
  Every deck includes one craftable commander card that represents the player’s leader. The commander’s data bundle may include unique inheritable traits and custom schematic code, which enhances its abilities.

• Unlimited Copies:
  There is no restriction on the number of copies of a card that a player can include within a deck.

• Dynamic Data Integrity:
  Each card within a deck retains its complete data bundle—including all static attributes, custom attributes, inheritable traits, and its schematic code. This ensures that every card’s behavior is fully defined and preserved, whether it is used in battle, crafting, or trading.

3.2 Deck Example (JSON)

{
  "deck_id": "D001",
  "player_id": "P123",
  "name": "Shadow Dominion",
  "commander": "9999",
  "cards": [
    "1001", "2001", "3001", "4001", "5001",
    "1002", "2002", "3002", "4002", "5002",
    "1003", "2003", "3003", "4003", "5003"
  ],
  "commander_details": {
    "id": "9999",
    "name": "Darklord, Master of Shadows",
    "picture": "darklord.jpg",
    "model": "darklord.obj",
    "schematic": {
      "code": "function executeAction(params){ /* commander-specific logic */ }",
      "version": "v2",
      "inheritance": true
    },
    "attack": 5,
    "health": 15,
    "cost": 3,
    "type": "Commander",
    "faction": "Eldritch",
    "skills": [
      {"id": "shadowStrike", "x": 7},
      {"id": "eldritchAura", "x": 3, "all": true}
    ],
    "placeable": false,
    "craftable": true,
    "convertible": false,
    "salvageable": false,
    "customAttributes": {
      "leadership": 10,
      "commandRadius": 5
    },
    "inheritableTraits": {
      "buff": 1.0
    },
    "action": {
      "version": "v2",
      "function": "executeAction",
      "parameters": {"position": "player"},
      "referenceSchematic": true
    }
  }
}

3.3 Deck Composition Details

• Comprehensive Data Inclusion:
  Every card in the deck is stored with its full data bundle. This includes the dynamic, code-driven schematic that defines its behavior.

• Strategic Flexibility:
  Players can mix and match cards that not only have varied combat statistics but also unique functions—some of which might be inherited when used in minting or crafting.

• Interoperability with Trading and Crafting:
  Since the complete data (including schematic code and inheritable traits) is preserved, any card used from a deck in crafting or traded between players retains its full functionality and history.

 

4. Sandbox Worlds and Crafting System

4.1 Voxel-Based Sandbox Worlds

• World Structure:
  Each tile on the strategic board is a procedurally generated voxel world with unique biomes (e.g., corrupted forests, volcanic plains).

• Interaction:
  Players mine blocks (dirt, cobble, corrupted stone, lava, etc.), build structures, and convert items into cards.

• Dynamic World-to-Card Conversion:
  Special Converter Stations in guild halls or designated zones allow players to convert world objects into cards (and vice versa) using cooldowns and resource costs to prevent abuse.

4.2 Crafting System

• Resource Gathering:
  Players collect materials (e.g., stone, lava gems) from voxel worlds.

• Crafting Recipes:
  Use in-game stations (e.g., forges) to combine raw materials into items or cards—such as creating a "Steel Sword" card from "Steel Ingot" and "Wood Handle" cards.

• Commander Crafting:
  A dedicated crafting pathway enables players to design and upgrade their commander cards, incorporating personalized features and mission-earned command bonuses.

 

5. Guild and Tile Mechanics

5.1 Tile-Based Board and Guild Conquest

• Map Layout:
  A hex-based strategic map where each tile is a unique sandbox world.

• Capture and Development:
  Guilds capture tiles via card battles and sabotage. Once captured, tiles generate resources (e.g., 10 crystals/hour) for guild progression.

• Tile Improvements:
  Cards (like "Mana Crystal" or "Wall") can be played to bolster defenses or increase resource output.

5.2 Guild Features

• Guild Structure:
  Hierarchical roles (leaders, officers, members) with shared treasuries for cards and resources.

• Diplomacy:
  Alliances, trade agreements, and coordinated sieges.

• Integration with ConcreteCMS:
  Guild management modules integrated as custom ConcreteCMS blocks that tie into user roles and permissions.

 

6. Battle and Strategic Systems

6.1 Turn-Based Combat Flow

• Phases:
  Draw → Resource Gain → Action (summoning, casting, deploying) → Combat Resolution → End Turn.

• Resource Management:
  Players utilize resource cards or mana accrued from tile generators.

• Circular Faction Dynamics:
  Faction multipliers (e.g., +50% damage against opposing faction types) are applied in combat calculations.

• Real-Time Integration:
  Use WebSocket-based communication (Socket.IO or Ratchet) for synchronizing combat actions, animations, and battle updates.

6.2 Commander and Multi-Deck Strategy

• Commander Role:
  The commander card, uniquely craftable and upgradeable, provides passive buffs and active abilities that influence battle outcomes.

• Deck Variety:
  Players can switch between multiple decks (each with 15 cards) to adapt strategies for PvP duels, guild skirmishes, or event battles.

 

7. Event System and Notification Controls

7.1 Player-Spawned Events

• Event Creation:
  Players can initiate events within their voxel worlds, triggering scenarios such as monster invasions.

• Invitations:
  Events support both public invites and invite-only modes, with the ability to send out notifications to selected friends or guild members.

• Event Mechanics:
  During an event, participants team up in real time to defeat the spawned monster. Rewards may include unique cards, resources, or XP boosts.

7.2 Notification System

• In-Game Notifications:
  Real-time alerts for battles, event invites, guild messages, and achievements.

• External Notifications:
  Integration with:

  • Email: Using SendGrid for mission updates, event reminders, and announcements.

  • SMS: Via Twilio for urgent alerts (e.g., ongoing sieges).

  • Social Sharing: APIs for Facebook, Twitter, and Discord to share achievements and event details.

• Granular Control:
  A dedicated settings page allows players to customize which notifications they receive and through which channels, with options to set quiet hours and filter types of alerts.

 

8. Technical Implementation

8.1 Frontend Technologies

• 2D UI & Deck Management:

  • Framework: Vue.js 3 or React 18.

  • State Management: Pinia (Vue) or Redux Toolkit (React).

  • Styling: Tailwind CSS or Bootstrap (with Vuetify/MUI for component libraries).

  • Build Tools: Vite or Webpack.

• 3D Voxel Rendering:

  • Rendering Engine: Three.js for WebGL.

  • Voxel Engine: voxel.js or a custom chunk-based renderer.

  • Physics: Cannon.js or Ammo.js.

• Real-Time Communication:

  • Options: Socket.IO (Node.js) or Ratchet (PHP) for live updates in battles, events, and chat.

• Integration with ConcreteCMS:

  • Enqueue JavaScript bundles via ConcreteCMS asset management.

  • Custom ConcreteCMS blocks to embed game UIs and 3D viewers.

8.2 Backend & Server Frameworks

• Core Framework:
  ConcreteCMS v9 as the main PHP platform.

• User and Data Management:

  • Utilize ConcreteCMS’s built-in user authentication for registration and login.

  • Custom packages/blocks to manage card data, decks, guilds, events, and notifications.

• Database:

  • MySQL/PostgreSQL: Store user profiles, card definitions, deck configurations, voxel chunk data, guild details, and notification preferences.

  • Redis (Optional): For caching session data and live game state.

• API Endpoints:

  • Develop RESTful or GraphQL APIs for card crafting, deck updates, event creation, and notification settings.

• Real-Time Services:

  • Optionally deploy a Node.js microservice for handling high-concurrency real-time events via Socket.IO.

8.3 Security and Optimization

• Security Measures:

  • Leverage ConcreteCMS’s CSRF protection and role-based permissions.

  • Server-side validation for all game actions (resource changes, card crafting, event initiation).

  • Use HTTPS/SSL for all data transmission.

• Performance:

  • Use chunk-based rendering in the voxel world.

  • Employ Redis caching and database indexing for high-traffic endpoints.

  • Load balancing with NGINX/HAProxy if necessary.

 

9. Community and Social Features

9.1 Social Integration

• In-Game:

  • Real-time chat, leaderboards, and guild forums integrated as ConcreteCMS blocks.

• External:

  • OAuth integrations with Facebook, Twitter, and Discord.

  • Social sharing tools for achievements and events.

9.2 Notification and Event Ecosystem

• Granular Notification Settings:

  • A user interface where players can toggle alerts (in-game, email, SMS, social) and set preferences.

• Event Invitations:

  • Real-time event invitations sent through both the game’s built-in social modules and external channels.

• Voice/Video Communication:

  • Integration of WebRTC (via PeerJS or SimpleWebRTC) for guild meetings and event coordination.

 

10. Card Creation and Customization

10.1 AI-Driven Art and Dynamic Data Attributes

• AI-Driven Art Generation:

  • Use an AI model (e.g., Stable Diffusion with a custom LoRA module) to generate custom card art in-game.

  • Players can generate unique art based on pre-trained image sets; premium players may pay to submit personal art that goes through an approval process.

• Dynamic and Extensible Attributes:

  • Attribute Flexibility:

    • Each card is represented as a JSON or XML data bundle containing a core set of attributes (id, name, picture, model, etc.), but also supports custom attributes.

    • New attributes can be added as needed, with each attribute including both a value and an optional code snippet that describes its functionality.

  • Embedded Code:

    • Cards include an embedded code segment (or a reference to a script/function) that defines additional behaviors—such as unique passive effects, activation conditions, or triggered events.

  • Inheritable Traits:

    • Certain attributes can be marked as inheritable, meaning that when a card is used as a component for minting a new card, these traits are passed on and cumulatively stack.

    • For example, a “buff” attribute with a value may be inherited from multiple component cards to form a more potent effect on the minted card.

  • Visibility and Tradeability:

    • The complete list of attributes (including those added dynamically) is visible in the card’s data structure. This transparency is essential, as the card’s functionality and assets (its image, model, schematics, etc.) are what players trade.

  • Non-Salvageable Flags:

    • Some cards may include a flag (e.g., salvageable: false) to prevent them from being broken down for components. This is especially relevant for unique or premium cards with custom attributes.

10.2 Crafting, Minting, and Salvage Mechanics

• Component-Based Crafting:

  • Cards are crafted by combining base components and even other cards. The resulting card can incorporate inherited traits from all of its components.

  • The cost for crafting higher attribute values increases exponentially to ensure balance.

• Minting with Custom States:

  • Players can mint a new card with any set of states they desire. The new card’s data bundle is generated dynamically, integrating inherited traits and any custom attribute modifications.

  • A dedicated API endpoint (e.g., POST /cards/mint) validates the resource cost and verifies that the new card’s JSON/XML adheres to the design schema.

• Salvage and Recycling:

  • Cards can be salvaged into their component parts, unless marked as non-salvageable.

  • The salvage system will break down a card into its fundamental attributes and components, allowing players to reuse these parts in new crafting recipes.

  • The process respects any inheritable attributes by properly decrementing or transferring cumulative values.

10.3 Integration with the Game Engine

• Action Routines and Code-Driven Behavior:

  • The card’s action attribute includes code references that trigger game engine routines—such as summoning units, placing structures, or activating special effects.

  • These routines are dynamically invoked based on the card’s current state and its embedded attributes.

• Extensible Attribute Schema:

  • The design allows for new attribute types (e.g., “energy regeneration,” “stealth bonus,” “area effect radius”) to be added without overhauling the underlying system.

  • Developers can update the attribute registry so that both the server-side and client-side understand and process new attribute codes.

 

11. Card Trading and Economy

11.1 Marketplace Infrastructure with Dynamic Card Attributes

• Trading as Data Exchange:

  • In Hellsword, the cards being traded include their full data bundle, meaning every traded card carries all its attributes and embedded functionality.

  • The marketplace supports transactions for cards that may include newly defined attributes, ensuring that upgrades, custom code, and inheritable traits are preserved during trades.

• Player-to-Player Trading and Auction House:

  • Players can list cards for sale using a secure trading interface. This interface shows the full breakdown of a card’s attributes, enabling informed trading.

  • Auction systems allow for bidding on cards with unique or enhanced attributes, with trade history logged and visible for reputation purposes.

11.2 Economic Integration and Component Markets

• In-Game Currency and Transaction Fees:

  • Trading is facilitated using in-game currencies (e.g., gold, premium currency). A transaction fee may be applied to each trade to help balance the economy.

  • The cost of cards reflects the exponential pricing model applied during minting—cards with higher cumulative attributes (inherited or custom) will trade at premium values.

• Component and Salvage Markets:

  • A secondary market exists for salvaged components. Cards that are broken down yield component parts, which are then available for purchase or trade.

  • This market supports dynamic pricing models, as the value of each component is determined by its inherited traits and overall rarity.

11.3 Trading System Features and API Integration

• Listings and Bidding:

  • Players can list cards with detailed attribute information. An API endpoint (e.g., POST /marketplace/list) accepts a card’s data bundle, ensuring that every aspect—down to custom code snippets and inheritable attributes—is recorded.

  • The bidding system supports both fixed-price and auction formats.

• Trade Validation and Secure Transactions:

  • All trades are processed via secure API calls with server-side validation to verify that the card data has not been tampered with.

  • An escrow system may be used to hold funds or components until the transaction is fully confirmed.

• Reputation and Transparency:

  • A detailed trade history is maintained for each player, which includes the complete data bundles of the traded cards.

  • Transparency in the card’s attribute data helps build reputation within the community, influencing trade prices and trust.

• Dynamic Market Adjustments:

  • The system can incorporate market algorithms to adjust prices based on trade volume and card rarity—ensuring that cards with new or enhanced attributes maintain their market value.

• API Endpoints and Data Models:

  • Develop endpoints such as GET /marketplace/cards, POST /marketplace/trade, and GET /marketplace/history that support full CRUD operations for trading cards.

  • The underlying data model for each trade includes fields for trade_id, seller_id, buyer_id, card_data (the full JSON/XML bundle), price, and timestamps.

 

Conclusion

This comprehensive prompt defines Hellsword as a richly layered game where dynamic cards—encoded as flexible JSON/XML data bundles—drive combat, crafting, and world-building. With decks of up to 15 cards (including a customizable, craftable commander) and support for multiple decks per player, the game offers deep strategic diversity. Integrated within a ConcreteCMS v9 environment, Hellsword leverages robust user management and modular content delivery, while its advanced event and notification systems ensure high community engagement. Combining a 2D management interface with immersive 3D voxel sandbox experiences and real-time, cross-channel notifications, Hellsword is positioned to deliver a unique, scalable, and socially integrated dark fantasy universe.