fvtt-adventures-with-emmy/AGENTS.md

Adventures with Emmy - System Overview & AI Agent Guidelines

Project Identity

System Name: Adventures with Emmy (AwE)
ID: fvtt-adventures-with-emmy
Version: 13.0.0 (Foundry VTT System)
Author: Uberwald (LeRatierBretonnien)
Purpose: STEM Education Role-Playing Game
License: MIT

---

System Overview

What is Adventures with Emmy?

Adventures with Emmy is a Foundry Virtual Tabletop (FVTT) system designed for educational role-playing with a focus on STEM (Science, Technology, Engineering, Mathematics) education. It provides a ruleset and digital tools for running tabletop RPGs that teach and reinforce STEM concepts through gameplay.

The system uses a d20-based mechanics with unique attributes, fields of study, specializations, and abilities that reflect scientific and mathematical disciplines.

Core Concepts

Concept	Description
Fields	Areas of study (Biologist, Chemist, Engineer, Mathematician, Physicist)
Attributes	Core character stats: Agility (AGI), Awareness (AWA), Fitness (FIT), Influence (INF)
Specializations	Sub-disciplines within fields
Archetypes	Character archetypes with prerequisite levels
Abilities	Powers and actions with costs (Δ = Action cost)
Flow Points	Resource for powering special abilities
Conditions	Status effects (Edge, Hampered, Inhibited, Jumbled, etc.)
Kits	Equipment bundles for character classes
Traits	Descriptive tags for abilities and items

Character Attributes

• Agility (AGI) - Physical dexterity and coordination
• Awareness (AWA) - Perception and observation skills
• Fitness (FIT) - Physical strength and endurance
• Influence (INF) - Social and leadership abilities

Each attribute has:

• boostLevel (0-7): Permanent boosts from background/field/level progression
• bonus: Manual +/- modifiers
• mod: Calculated as level + boostLevel + bonus
• dc: Difficulty Class = 10 + mod

---

Project Structure

fvtt-adventures-with-emmy/
├── adventures-with-emmy.mjs          # Main system entry point
├── system.json                       # System manifest
├── module/
│   ├── config/
│   │   ├── system.mjs                # System constants (ATTRIBUTES, CONDITIONS, TRAITS, etc.)
│   │   └── trait-descriptions.json   # Tooltip descriptions for traits
│   ├── models/
│   │   ├── _module.mjs               # Model exports
│   │   ├── character.mjs             # Hero character data model
│   │   ├── creature.mjs              # NPC/creature data model
│   │   ├── ability.mjs               # Ability item model
│   │   ├── field.mjs                 # Field of study model
│   │   ├── specialization.mjs        # Specialization model
│   │   ├── archetype.mjs             # Archetype model
│   │   ├── background.mjs            # Background model
│   │   ├── kit.mjs                   # Kit/equipment bundle model
│   │   ├── weapon.mjs                # Weapon model
│   │   ├── equipment.mjs             # Equipment model
│   │   ├── skill.mjs                 # Skill model
│   │   └── effect.mjs                # Effect model
│   ├── documents/
│   │   ├── _module.mjs               # Document exports
│   │   ├── actor.mjs                 # Actor document class
│   │   ├── item.mjs                  # Item document class
│   │   ├── roll.mjs                  # Custom Roll class with outcome calculation
│   │   ├── chat-message.mjs          # Chat message handling
│   │   └── combatant.mjs             # Combatant document
│   └── applications/
│       ├── _module.mjs               # Application exports
│       ├── sheets/                   # Character/Item sheet classes
│       │   ├── base-actor-sheet.mjs
│       │   ├── character-sheet.mjs
│       │   ├── creature-sheet.mjs
│       │   ├── base-item-sheet.mjs
│       │   └── [all item type sheets]
│       └── hud/                       # Token Action HUD integration
│           ├── constants.js          # HUD group definitions
│           ├── system-manager.js     # HUD system manager
│           ├── action-handler.js     # Builds action lists for HUD
│           ├── roll-handler.js       # Handles roll actions from HUD
│           ├── defaults.js            # Default HUD settings
│           └── settings.js            # HUD-specific settings
├── templates/                        # Handlebars templates
│   ├── chat-message.hbs              # Roll/damage chat output
│   ├── roll-dialog.hbs               # Roll configuration dialog
│   ├── ability-use.hbs               # Ability usage chat card
│   ├── character-*.hbs               # Character sheet tabs
│   ├── creature-*.hbs                # Creature sheet tabs
│   └── [item templates]              # Individual item sheet templates
├── lang/
│   └── en.json                       # English localization
├── css/
│   └── adventures-with-emmy.css      # System styles
├── packs-system/                     # Compendium packs
├── assets/                           # Static assets (condition icons, etc.)
├── gulpfile.js                       # CSS compilation
├── eslint.config.mjs                 # ESLint configuration
└── package.json                      # Development dependencies

File Counts

• Source Files: 66 (excluding node_modules)
  • Models: 12
  • Documents: 5
  • Applications/Sheets: 12
  • Applications/HUD: 6
  • Templates: 24
  • Config: 2

---

Technical Architecture

Technology Stack

Component	Technology
Platform	Foundry Virtual Tabletop v13
Language	JavaScript (ES Modules - .mjs)
Templates	Handlebars (.hbs)
Styles	CSS (compiled from LESS via Gulp)
Data Format	JSON
Module System	ES6 Modules

Integration Points

1. Token Action HUD Core Module

   • Required module: token-action-hud-core v2.0+
   • Provides action buttons for characters in the HUD
   • Integration via tokenActionHudCoreApiReady hook
   • Action groups: attributes, hp, flow, weapons, conditions, abilities, kits, utility

2. Foundry VTT API

   • Extends Actor, Item, Roll, ChatMessage, Combatant
   • Custom data models using foundry.abstract.TypeDataModel
   • Uses Foundry's schema field system

3. Custom Roll System

   • Extended AwERoll class with outcome calculation
   • Degrees of success: Critical Success, Success, Failure, Critical Failure
   • Support for rolling twice (take higher/lower)
   • Automatic damage roll on hit

Data Models

Actor Types

• character - Player heroes with full STEM capabilities
• creature - NPCs and monsters

Item Types

• specialization - Field specializations
• ability - Character abilities with costs
• field - Field of study items
• archetype - Character archetypes
• background - Character backgrounds
• kit - Equipment kits
• weapon - Weapon items
• equipment - General equipment
• skill - Skill items
• effect - Active effects

---

Key Features

1. Attribute System

• Four core attributes (Agility, Awareness, Fitness, Influence)
• Each attribute has boost levels (0-7) from progression
• Manual bonus/penalty support
• Derived modifier and DC calculations

2. Roll Mechanics

• d20-based checks with modifiers
• Automatic outcome calculation (critical success/failure based on DC ±10)
• Natural 20/1 auto-upgrade/downgrade
• Support for situational bonuses (-5 to +5)
• Knowledge bonuses from items
• Condition bonuses/penalties
• Roll twice options (take higher/lower)

3. Action Economy

• Δ (Delta) - Action cost system
• Costs: Free, One (Δ), Two (ΔΔ), Three (ΔΔΔ), Reaction (↩), Variable
• Flow Point costs for special abilities
• Daily ability tracking

4. Combat Integration

• Weapon attack rolls with automatic damage
• Critical hits double damage dice
• Condition system with status effect icons
• Token Action HUD support

5. STEM-Specific Features

• Fields: Biologist, Chemist, Engineer, Mathematician, Physicist
• Mathematician Subfields: Electromagnetic, Geometry, Gravity, Numerical, Paradox, Probability
• Engineer Specializations: Computer, Electrical, Mechanical
• Trait System: Extensive tagging for abilities (attack, flow, hypothesis, intensive, kit, linguistic, manipulate, review, traversal, velocity, etc.)

6. Resource Management

• Hit Points (HP) with temp HP
• Flow Points (FP) with temp FP
• Daily ability tracking
• Long rest mechanics

7. Token Action HUD Features

• Attribute displays with modifiers
• HP tracking with +/-
• Flow Point tracking with +/-
• Weapon lists with attack modifiers
• Condition toggles
• Ability lists with costs and usage tracking
• Kit usage
• Utility actions (Long Rest, End Turn)

---

Development Standards

Code Style

1. File Naming:

   • Module files: kebab-case.mjs
   • Classes: PascalCase with AwE prefix (e.g., AwECharacter)
   • Constants: UPPER_SNAKE_CASE
   • Variables/Functions: camelCase

2. ESLint Configuration:

   • Uses @eslint/js with custom config in eslint.config.mjs
   • Includes eslint-plugin-jsdoc for documentation
   • Prettier integration for formatting

3. Imports:

   • Use ES6 import/export syntax
   • Relative paths from module root
   • Module aggregation in _module.mjs files

4. Documentation:

   • JSDoc comments for classes and methods
   • Inline comments for complex logic
   • English language for code comments

File Organization

• models/: Data schema definitions
• documents/: Foundry document classes
• applications/: UI components and sheets
• templates/: Handlebars templates
• config/: System configuration and constants

Build Process

• CSS: Compiled from LESS using Gulp
• No Bundling: Files loaded individually via Foundry's ES module system
• Hot Reload: Configured for CSS, HBS, JSON files

---

AI Agent Guidelines

For Code Modification Agents

✅ DO:

1. Follow Existing Patterns

   • Match the code style and structure of existing files
   • Use the same naming conventions (AwE prefix for classes)
   • Maintain consistent import/export patterns

2. Use Foundry VTT APIs

   • Extend appropriate base classes (TypeDataModel, Actor, Item, etc.)
   • Use foundry.data.fields for schema definitions
   • Follow Foundry's data model patterns

3. Maintain Data Integrity

   • Always define schemas in model files
   • Use proper field types (NumberField, StringField, SchemaField, etc.)
   • Set appropriate initial values and constraints (min/max)

4. Preserve Existing Functionality

   • Don't modify files without understanding their dependencies
   • Test changes against the full system
   • Ensure backward compatibility

5. Document Changes

   • Add JSDoc comments for new methods
   • Update any affected documentation
   • Note any breaking changes

❌ DON'T:

1. Modify Core Foundry Files

   • Only modify files within the fvtt-adventures-with-emmy directory
   • Never edit Foundry VTT core files

2. Break Existing Schemas

   • Don't change field types without migration plans
   • Don't remove required fields
   • Don't change field names without updating all references

3. Introduce External Dependencies

   • Only use libraries already in package.json
   • Avoid jQuery (use native DOM APIs)
   • Prefer Foundry's built-in utilities

4. Hardcode Localization Strings

   • Use game.i18n.localize() for all user-facing text
   • Add new strings to lang/en.json
   • Use localization keys, not raw text

5. Modify Without Testing

   • Always verify changes work in Foundry VTT
   • Test with both character and creature actors
   • Test with various item types

For Token Action HUD Agents

HUD Integration Rules:

1. Dependency:

   • All HUD code is in module/applications/hud/
   • Requires token-action-hud-core v2.0+
   • Integration via tokenActionHudCoreApiReady hook

2. Action Groups:

   • Defined in constants.js
   • Built in action-handler.js
   • Each group has: id, name, type

3. Adding New Actions:

   • Add to appropriate build method in action-handler.js
   • Use encoded values with delimiter (e.g., ['ability', id].join(this.delimiter))
   • Include proper tooltips and info displays

4. Roll Handlers:

   • Defined in roll-handler.js
   • Registered in system-manager.js
   • Handle roll actions from HUD buttons

For Documentation Agents

Documentation Standards:

1. File Location:

   • System documentation: _docs/ directory
   • API documentation: Include in JSDoc comments
   • User documentation: Markdown files in _docs/

2. Code Documentation:

   • Use JSDoc format
   • Document parameters and return types
   • Include examples where helpful

3. User Documentation:

   • Explain STEM concepts clearly
   • Provide examples for gameplay
   • Include screenshots where possible

For Testing Agents

Test Areas:

1. Roll Mechanics

   • Test outcome calculation (critical success/failure boundaries)
   • Test modifier application
   • Test condition bonuses
   • Test roll twice functionality

2. Data Models

   • Test schema validation
   • Test derived data calculation
   • Test default values

3. Sheets

   • Test rendering with various data states
   • Test form submissions
   • Test tab switching

4. HUD Integration

   • Test action building for different actor types
   • Test action execution
   • Test visibility and permissions

5. Combat

   • Test weapon attack rolls
   • Test damage calculation
   • Test critical hits
   • Test condition application

---

Common Tasks

Adding a New Item Type

1. Create Model (module/models/new-type.mjs):

   import { SYSTEM } from "../config/system.mjs"
   
   export default class AwENewType extends foundry.abstract.TypeDataModel {
     static defineSchema() {
       const fields = foundry.data.fields
       return {
         description: new fields.HTMLField({ required: true, textSearch: true }),
         // Add other fields...
       }
     }
   
     prepareDerivedData() {
       // Calculate derived fields
     }
   }
   

2. Export in _module.mjs:

   export { default as AwENewType } from "./new-type.mjs"
   

3. Add to system.json:

   "Item": {
     "newType": { "htmlFields": ["description"] }
   }
   

4. Create Sheet (module/applications/sheets/new-type-sheet.mjs):

   • Extend base-item-sheet.mjs
   • Define template path
   • Handle form submission

5. Register Sheet in adventures-with-emmy.mjs:

   foundry.documents.collections.Items.registerSheet(
     "fvtt-adventures-with-emmy", 
     applications.AwENewTypeSheet, {
       types: ["newType"], 
       makeDefault: true 
     }
   )
   

6. Create Template (templates/new-type.hbs):

   • Use existing templates as reference
   • Include all relevant fields

7. Add Localization in lang/en.json:

   "TYPES.Item.newType": "New Type",
   "AWEMMY.Item.NewType": "New Type"
   

Adding a New Attribute

1. Add to config/system.mjs:

   export const ATTRIBUTES = {
     ...existing,
     newAttr: { id: "newAttr", abbrev: "NEW", label: "AWEMMY.Attribute.NewAttr" }
   }
   

2. Update Character Model:

   • Modify module/models/character.mjs to include new attribute in schema

3. Update Sheets:

   • Add attribute display to character sheet templates
   • Add attribute to creature sheet if applicable

4. Update HUD:

   • Add to action-handler.js #buildAttributes() method
   • Add to constants.js if needed

5. Add Localization:

   • Add label to lang/en.json

Adding a New Condition

1. Add to config/system.mjs:

   export const CONDITIONS = {
     ...existing,
     newCondition: { id: "newCondition", label: "AWEMMY.Condition.NewCondition" }
   }
   

2. Create Icon:

   • Add SVG file to assets/conditions/newCondition.svg

3. Update HUD:

   • Add to #buildConditions() in action-handler.js

4. Add Localization:

   • Add label and description to lang/en.json

5. Handle in Actor:

   • Add condition bonus logic to actor.mjs if needed

---

Best Practices

Performance

1. Minimize DOM Queries:

   • Cache selectors when possible
   • Use event delegation for dynamic elements

2. Async/Await:

   • Use async/await for all Foundry API calls
   • Handle errors appropriately

3. Data Access:

   • Cache frequently accessed data
   • Use this.actor instead of game.actors.get() when available

User Experience

1. Feedback:

   • Provide notifications for important actions
   • Use ui.notifications.info/warn/error appropriately

2. Accessibility:

   • Use semantic HTML in templates
   • Provide alt text for images
   • Ensure sufficient color contrast

3. Localization:

   • Always use localization keys
   • Support right-to-left languages in templates

Security

1. User Input:

   • Sanitize all user input
   • Use Foundry's HTML sanitization for rich text

2. Permissions:

   • Check permissions before performing actions
   • Use game.user.isGM for GM-only features

3. Data Validation:

   • Validate all incoming data
   • Use schema validation for model data

---

Debugging Tips

Common Issues

1. Schema Errors:

   • Check field definitions match usage
   • Verify initial values are valid
   • Ensure required fields are present

2. Roll Calculation Problems:

   • Verify modifier calculation in roll.mjs
   • Check outcome computation logic
   • Test with known DC values

3. HUD Not Showing Actions:

   • Verify Token Action HUD Core is installed
   • Check tokenActionHudCoreApiReady hook fires
   • Ensure action groups are registered

4. Sheet Rendering Issues:

   • Check template paths are correct
   • Verify data is passed to template
   • Use browser dev tools to inspect rendered HTML

Debugging Tools

1. Foundry Console:

   • CONFIG.debug = true for additional logging
   • Use console.log() for debugging (visible in F12 console)

2. Browser Dev Tools:

   • Inspect elements and styles
   • Check network requests
   • Debug JavaScript execution

3. Foundry VTT Developer Mode:

   • Enable in Foundry settings
   • Provides additional debugging capabilities

---

Resources

Official Documentation

• Foundry VTT Documentation
• Foundry VTT API Documentation
• Token Action HUD Documentation

Project Resources

• Repository: https://www.uberwald.me/gitea/uberwald/fvtt-adventures-with-emmy.git
• Issue Tracker: Use repository issue tracker
• Discord: LeRatierBretonnien (Author)

Development Tools

• ESLint: For code quality checking
• Prettier: For code formatting
• Gulp: For CSS compilation
• Foundry VTT CLI: For packaging and distribution

---

Quick Reference

System Constants

Constant	Location	Purpose
SYSTEM_ID	config/system.mjs	System identifier
ATTRIBUTES	config/system.mjs	Core character attributes
CONDITIONS	config/system.mjs	Status effects
ABILITY_COST	config/system.mjs	Action cost types
ABILITY_TYPE	config/system.mjs	Ability categories
TRAITS	config/system.mjs	Allowed trait list
TRAIT_DESCRIPTIONS	trait-descriptions.json	Trait tooltips

Key Methods

Class	Method	Purpose
AwEActor	rollWeapon()	Roll weapon attack
AwEActor	rollAttribute()	Roll attribute check
AwEActor	useAbility()	Activate an ability
AwEActor	useKit()	Use a kit item
AwEActor	longRest()	Perform long rest
AwERoll	prompt()	Show roll dialog
AwERoll	computeOutcome()	Calculate success degree

Hooks

Hook	Location	Purpose
init	adventures-with-emmy.mjs	System initialization
ready	adventures-with-emmy.mjs	System ready
tokenActionHudCoreApiReady	adventures-with-emmy.mjs	HUD integration
renderChatMessageHTML	adventures-with-emmy.mjs	Damage roll buttons

---

Version History

• v13.0.0 - Current version (Foundry VTT v13 compatibility)
• Previous versions support Foundry VTT v12 and earlier

---

Contact & Support

For questions, issues, or contributions:

• Author: LeRatierBretonnien (Discord)
• Repository: https://www.uberwald.me/gitea/uberwald/fvtt-adventures-with-emmy.git
• Foundry VTT Package: Available in Foundry's package manager

---

This AGENTS.md file provides comprehensive guidance for AI agents and developers working on the Adventures with Emmy system. Always refer to the latest version of this file and the actual source code for the most accurate information.