Mechanics Folder

Purpose

Documentation for Path of Exile game mechanics, systems, and content.

Folder Structure

mechanics/
├── skills/          # Skill gems and abilities
├── items/           # Unique items and equipment
├── leagues/         # League mechanics
├── crafting/        # Crafting systems
└── atlas/           # Atlas and endgame systems

Subfolder Guidelines

skills/

• Skill gems and active abilities
• Support gems
• Vaal skills
• Template: templates/skill-template.md

items/

• Unique items
• Keystones and notables
• Equipment systems
• Template: templates/item-template.md

leagues/

• League-specific mechanics
• Mechanics that were added in leagues
• Template: templates/league-template.md

crafting/

• Crafting methods and systems
• Currency usage guides
• Template: templates/mechanic-template.md

atlas/

• Atlas passive tree
• Endgame systems
• Map mechanics
• Template: templates/mechanic-template.md

Naming Conventions

File Names

• Format: [mechanic-name].md (kebab-case)
• Use full name, not abbreviations (unless widely known)

Examples:

• righteous-fire.md
• atlas-passive-tree.md
• essence-crafting.md
• the-brass-dome.md (for unique items with "The")
• energy-shield.md

Template Requirements

Template varies by subfolder - check subfolder index.md

Common Required Frontmatter:

template: "templates/[appropriate-template].md"
document_type: "skill|item|mechanic|league"
title: "[Mechanic Name]"
status: "draft|review|published|outdated"
author: "[Your Name]"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
tags: ["tag1", "tag2"]
league: "3.25"
patch: "3.25.1"

Creation Workflow

1. Determine Subfolder

Choose appropriate category: skills, items, leagues, crafting, or atlas

2. Check Subfolder Index

Read("mechanics/[subfolder]/index.md")

3. Get Template

Read("templates/[appropriate-template].md")

4. Create Document

Write("mechanics/[subfolder]/[mechanic-name].md", content)

Path Conventions

Always use absolute paths from project root:

✅ CORRECT:

relationships:
  synergizes_with:
    - path: "mechanics/skills/righteous-fire.md"
      title: "Righteous Fire"

❌ INCORRECT:

relationships:
  synergizes_with:
    - path: "../skills/righteous-fire.md"

Relationship Types

Common Relationships

• requires / required_by - Hard dependencies
• synergizes_with - Works well together
• countered_by / counters - Interactions
• alternative_to - Similar mechanics
• used_by - Which builds use this

Tags Guidelines

Category Tags

• System: combat, defense, crafting, currency, endgame
• Type: skill, support, item, unique, mechanic
• Damage: physical, fire, cold, lightning, chaos
• Content: mapping, bossing, league-mechanic

Example Tag Set

# For a skill
tags: ["fire", "spell", "aoe", "dot", "skill"]

# For an item
tags: ["unique", "body-armour", "armour", "physical", "item"]

# For a mechanic
tags: ["endgame", "atlas", "passive-tree", "mechanic"]

Quality Checklist

Before creating a mechanic document:

• [ ] Read this index.md
• [ ] Read subfolder-specific index.md
• [ ] Used correct template for content type
• [ ] Included template: field in frontmatter
• [ ] Followed naming convention (kebab-case)
• [ ] Set current league and patch version
• [ ] Used absolute paths for relationships
• [ ] Added descriptive tags
• [ ] Set appropriate status
• [ ] Verified uniqueness (no duplicates)

Content Guidelines

What to Include

• Clear explanation of the mechanic
• How it works in-game
• Interactions with other mechanics
• Current meta relevance
• Patch history (if significant changes)
• Links to related builds/items

Writing Style

• Clear and concise
• Use game terminology correctly
• Include specific numbers and stats
• Note any league or patch-specific behavior
• Link to official wiki for deep details

Examples

Good File Names

• righteous-fire.md
• the-brass-dome.md
• essence-crafting.md
• maven-invitations.md
• atlas-passive-tree.md

Bad File Names

• RF.md (use full name)
• Righteous Fire.md (has spaces)
• righteous_fire.md (use kebab-case, not snake_case)
• mechanic1.md (meaningless)

Additional Resources

• POE Wiki: https://www.poewiki.net/
• Craft of Exile: https://craftofexile.com/
• POE DB: https://poedb.tw/