Relic Overview

Relic - Legendary Tool Progression System

Overview

Relic transforms ordinary tools into legendary artifacts that grow in power alongside their wielder. Through use and dedication, tools gain Renown (experience), unlock Inscription Sockets, and can be imbued with powerful Inscriptions that enhance their capabilities.

Core Philosophy

Tools as Companions: Your pickaxe, sword, or hoe becomes a legendary artifact with its own story
Modular Progression: Customize your relic’s abilities through configurable inscriptions
Legendary Growth: Tools become more powerful and unique over time
Server Flexibility: Fully JSON-configured for any server’s needs

Core Concepts

🗿 Relics

Any item can become a Relic by using a special upgrade item (likely via Filament integration):

Standard tools (pickaxe, axe, sword, hoe, shovel, fishing rod)
Armor pieces
Custom/modded items (configurable)

Once upgraded, the item becomes a Relic and begins tracking usage and progression.

✨ Renown (Experience System)

Relics gain Renown through use:

Mining blocks (pickaxe, shovel)
Chopping trees (axe)
Harvesting crops (hoe)
Defeating entities (sword)
Fishing catches (fishing rod)
Taking damage (armor)

Renown accumulates and levels up the Relic, unlocking new capabilities.

🔮 Inscription Sockets

As Relics gain levels, they unlock Inscription Sockets - slots where Inscriptions can be installed:

Number of sockets determined by level thresholds
Example: Level 5 = 1 socket, Level 15 = 2 sockets, Level 30 = 3 sockets (configurable)
Each socket can hold one Inscription

🌟 Essence Capacity

Every Relic has an Essence Capacity - the amount of mystical power it can contain:

Base capacity determined by item type (diamond > iron > stone)
May increase with levels (configurable)
Limits how many/which Inscriptions can be installed

📜 Inscriptions (Modifications)

Inscriptions are the actual modifications installed into Relics (similar to Journey’s Buff system):

JSON-configured by server admins
Have an Essence Cost (consume Essence Capacity)
Can be simple (stat modifiers) or complex (scripted behaviors)
Organized into categories/tiers

Thematic Terminology

Concept	Thematic Name	Description
Upgraded Item	Relic	A legendary tool imbued with power
Experience	Renown	Fame/legend the tool gains through deeds
Modification Slots	Inscription Sockets	Places where power can be inscribed
Modifications	Inscriptions	Mystical enhancements etched onto the relic
Capacity/Weight	Essence Capacity	How much power the relic can contain
Mod Cost	Essence Cost	How much essence an inscription requires
Level	Relic Level	The legendary status of the relic

Inscription System

Inscription Types

1. Attribute Inscriptions (Simple)

Modify item/player attributes:

{
  "id": "keen_edge",
  "name": "Keen Edge",
  "description": "Sharpens the blade, increasing damage",
  "essence_cost": 2,
  "category": "combat",
  "tier": "common",
  "effects": {
    "attribute_modifiers": [
      {
        "attribute": "generic.attack_damage",
        "value": 2.0,
        "operation": "ADD"
      }
    ]
  }
}

2. Scripted Inscriptions (Advanced)

Execute custom logic on events:

{
  "id": "flamestrike",
  "name": "Flamestrike",
  "description": "Chance to ignite enemies on hit",
  "essence_cost": 4,
  "category": "combat",
  "tier": "rare",
  "effects": {
    "on_entity_hit": {
      "conditions": ["math.random() < 0.25"],
      "scripts": [
        "target.set_on_fire(5);"
      ],
      "commands": [
        "/particle minecraft:flame ~ ~1 ~ 0.3 0.3 0.3 0.1 20"
      ]
    }
  }
}

3. Passive Inscriptions

Always-active effects:

{
  "id": "fortune_glyph",
  "name": "Fortune Glyph",
  "description": "Increases drop multiplier",
  "essence_cost": 5,
  "category": "utility",
  "tier": "epic",
  "effects": {
    "enchantment_boost": {
      "enchantment": "minecraft:fortune",
      "levels": 1
    }
  }
}

Inscription Categories

Organize inscriptions thematically:

Combat: Damage, lifesteal, criticals
Efficiency: Speed, durability, auto-smelt
Utility: Fortune, looting, reach
Elemental: Fire, ice, lightning effects
Mystical: Teleportation, particle effects, unique behaviors

Inscription Tiers

Balance power through rarity:

Common (1-2 essence): Basic stat boosts
Uncommon (2-3 essence): Moderate enhancements
Rare (3-5 essence): Powerful effects
Epic (5-7 essence): Game-changing abilities
Legendary (8+ essence): Ultimate power (may exceed most relics’ capacity)

Catalyst System

Relic Catalysts (Filament Behaviours)

Relic Catalysts are Filament item behaviours that transform ordinary tools into relics. Each catalyst has hidden stats that are rolled when obtained and determine the quality of the resulting relic.

Hidden Stats System

When a catalyst is obtained, it rolls stats from defined ranges:

Base Stats:

Essence Capacity: Rolled within min/max range (e.g., 12-20 for diamond tier)
Starting Level: Usually 0, but rare catalysts may grant bonus levels
Socket Unlock Curve: May modify socket unlock levels

Modifiers (Rare):

Inscription Boosts: Chance for specific inscription categories to cost less essence
- Example: “Mining Focus” - Mining inscriptions cost -1 essence
- Example: “Combat Mastery” - Combat inscriptions cost -2 essence
Pre-installed Inscriptions: Low chance to start with inscriptions already installed
- Example: 5% chance for “Swift Mining I”
- Example: 1% chance for “Fortune Glyph”
Bonus Sockets: Very rare chance for +1 max socket
Renown Multipliers: Rare chance for +10-25% renown gain

Catalyst Types

Different catalyst types (Filament behaviours) define different stat ranges and modifier pools:

Common Catalyst:

Essence: 10-15
No modifiers
Basic transformation

Rare Catalyst:

Essence: 15-20
20% chance for one modifier
Enhanced potential

Epic Catalyst:

Essence: 18-25
50% chance for one modifier
10% chance for second modifier
Guaranteed high essence

Legendary Catalyst:

Essence: 22-30
Guaranteed two modifiers
30% chance for third modifier
Maximum potential

Identification Lens

The Identification Lens is another Filament item behaviour that reveals catalyst hidden stats.

Before Identification:

Mysterious Relic Catalyst
<gray>Right-click with an Identification Lens to reveal its properties

After Identification:

<gold>Rare Relic Catalyst
<gray>Essence Capacity: <aqua>17
<gray>
<yellow>Modifiers:
  <green>⚡ Mining Focus
  <dark_gray>Mining inscriptions cost -1 essence

Identification Process:

Hold catalyst in hand
Right-click with Identification Lens
Lens is consumed
Catalyst stats are permanently revealed
Name updates with quality/modifiers

Lens can also identify already-awakened relics to see their catalyst roll without awakening.

Progression Flow

1. Catalyst Acquisition

Player obtains a Relic Catalyst:

Found in loot chests
Purchased from vendors
Reward from quests/bosses
Crafted (if configured)

Catalyst appears unidentified with hidden stats.

2. Catalyst Identification (Optional)

Player uses an Identification Lens:

Reveals catalyst quality
Shows essence capacity roll
Displays any special modifiers
Helps player decide which tools to awaken

3. Relic Awakening

Player uses the Relic Catalyst on a tool:

Tool transforms into a Relic
Inherits catalyst’s hidden stats
Begins tracking Renown
Displays current level (0) and empty sockets
Shows Essence Capacity (from catalyst roll)

4. Gaining Renown

Player uses the Relic normally:

Each action grants Renown based on configuration
Progress bar/notification shows Renown gain
Level up notifications when thresholds reached
Catalyst modifiers may boost renown gain

5. Unlocking Sockets

When Relic reaches specific levels:

Unlock new Inscription Sockets
Notification: “Your relic has unlocked a new socket!”
Access Inscription GUI to install modifications
Catalysts with bonus socket modifiers unlock additional sockets

6. Installing Inscriptions

Player opens Relic Inscription GUI:

Shows available sockets (locked/unlocked)
Displays Essence Capacity (used/total)
Browse available Inscriptions (obtained through various means)
Install Inscriptions if essence allows
Catalyst modifiers may reduce inscription costs
Remove/swap Inscriptions (may have costs/restrictions)

7. Legendary Status

Max-level Relics with powerful Inscription combinations and lucky catalyst rolls become legendary tools worth their own stories

GUI System

Relic Inscription Interface

Main GUI for managing inscriptions:

╔═══════════════════════════════════════════╗
║         RELIC INSCRIPTION CHAMBER         ║
╠═══════════════════════════════════════════╣
║                                           ║
║    [RELIC PREVIEW]      ESSENCE: █████░░  ║
║    Diamond Pickaxe      12/15 Used        ║
║    Level: 23                              ║
║    Renown: 45,230/50,000                  ║
║                                           ║
║    INSCRIPTION SOCKETS:                   ║
║    ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐       ║
║    │ [📜] │ │ [📜] │ │ [📜] │ │  🔒  │       ║
║    └─────┘ └─────┘ └─────┘ └─────┘       ║
║     5 Ess   4 Ess   3 Ess   Locked       ║
║                                           ║
║    AVAILABLE INSCRIPTIONS:                ║
║    [Browse] [Filter: All ▼] [Search]     ║
║                                           ║
╚═══════════════════════════════════════════╝

Inscription Browser

Sub-GUI for selecting inscriptions:

Filter by category, tier, essence cost
Preview effects before installing
Show requirements (if any)
Display lore/descriptions

Inscription Acquisition

Players obtain Inscriptions through various means (configurable):

1. Default Unlocked

Basic inscriptions available to all players from the start

2. Level Unlocks

Unlock inscriptions at specific Relic levels

{
  "id": "master_strike",
  "unlock_requirement": {
    "relic_level": 50
  }
}

3. Discovery System (Odyssey Integration?)

Find inscriptions through gameplay:

Defeating bosses
Exploring structures
Fishing up treasures
Mining rare ores

4. Journey Integration

Unlock inscriptions by completing Journey tasks:

{
  "id": "champions_blessing",
  "unlock_requirement": {
    "journey_task": "defeat_elite_four"
  }
}

5. Crafting System

Craft inscription scrolls/tomes using recipes

6. Vendor/Economy

Purchase inscriptions with currency (Impactor integration)

Scripting Events

Inscriptions can hook into various events:

Tool Events

on_block_break - When breaking a block
on_block_place - When placing a block
on_entity_hit - When hitting an entity
on_player_hurt - When player takes damage (armor relics)
on_item_use - When right-clicking
on_item_swing - When left-clicking (miss)
on_fishing_catch - When catching something

Contextual Variables

Available in MoLang scripts:

// Player context
q.player.health
q.player.level
q.player.gamemode

// Tool context
q.relic.level
q.relic.renown
q.relic.durability

// Event context
q.block.type          // on_block_break
q.entity.type         // on_entity_hit
q.target.health       // on_entity_hit
q.damage.amount       // on_player_hurt

Example Advanced Inscription

{
  "id": "mining_frenzy",
  "name": "Mining Frenzy",
  "description": "Breaking ore grants speed and haste briefly",
  "essence_cost": 6,
  "category": "efficiency",
  "tier": "epic",
  "effects": {
    "on_block_break": {
      "conditions": [
        "q.block.has_tag('c:ores')"
      ],
      "scripts": [
        "player.add_effect('minecraft:speed', 100, 1);",
        "player.add_effect('minecraft:haste', 100, 1);"
      ],
      "commands": [
        "/playsound minecraft:block.anvil.use player @s ~ ~ ~ 0.5 2.0"
      ],
      "particles": {
        "type": "minecraft:enchant",
        "count": 10,
        "spread": [0.5, 0.5, 0.5]
      }
    }
  }
}

Configuration Structure

Main Config (`config/relic/config.json`)

Core mod settings only - catalysts, inscriptions, and relics are Filament behaviours.

{
  "enabled": true,

  "renown_sources": {
    "block_break": {
      "base_renown": 1,
      "ore_multiplier": 3,
      "rare_ore_multiplier": 5
    },
    "entity_kill": {
      "base_renown": 5,
      "player_multiplier": 20,
      "boss_multiplier": 50
    }
  },

  "socket_unlocks": [
    { "level": 5, "sockets": 1 },
    { "level": 15, "sockets": 2 },
    { "level": 30, "sockets": 3 },
    { "level": 50, "sockets": 4 }
  ],

  "level_curve": {
    "type": "exponential",
    "base_renown": 100,
    "exponent": 1.15
  }
}

Filament Behaviours

All content is defined as Filament behaviours in data packs:

Catalyst Types (data/<namespace>/filament/item/relic_catalysts/)

Define essence ranges
Modifier pools and chances
Name formatting (MiniMessage)
Quality tiers

Identification Lens (data/<namespace>/filament/item/identification_lens.json)

Single behavior for all identification
Consumable on use
Reveals catalyst hidden stats

Inscriptions (data/<namespace>/filament/item/inscriptions/)

Individual inscription behaviors
Effects and scripts
Category and tier

Relic Templates (data/<namespace>/filament/item/relics/)

Pre-configured legendary relics
Fixed or rolled stats
Special properties

Cross-Mod Integration

Journey

Tasks can require Relic levels: "relic.level >= 30"
Tasks reward inscriptions
Inscriptions can execute Journey scripts
MoLang functions: q.relic.has_inscription('id'), q.relic.level

Levelables

Share Renown/XP gain with Journey levelables
Inscriptions that boost levelable progression
Unlock inscriptions through levelable milestones

Venture

Send tools on ventures to gain Renown passively
Venture rewards include inscriptions
Tool-specific ventures (pickaxe ventures, sword ventures)

Witness

Cinematic sequences when awakening relics
Camera effects on legendary inscription activations

Tarot

Bank system for storing inscriptions
Shiny boost system for rare inscription drops

Bloom

Lures that attract inscription-granting mobs
Special bloom effects for relic users

Outbreaks

Outbreak participation rewards inscriptions
High-level relics boost outbreak rewards

Technical Considerations

Data Storage

Relic data stored in NBT on items
Track: level, renown, sockets, installed inscriptions
Persistent across server restarts

Performance

Event listeners only active for held/worn relics
Script execution limits to prevent lag
Configurable max relics per player

Filament Integration

Likely use Filament for:

Relic awakening items (Catalyst)
Inscription scrolls/tomes
Special relic upgrade materials

Balance Considerations

Essence costs prevent “god tools”
Higher tier inscriptions require more essence
Some inscriptions may be mutually exclusive
Socket unlocks require significant time investment
Renown gain balanced to prevent instant max-level

Example Progression Path

Early Game (Levels 1-10)

Stone Pickaxe Relic

Essence Capacity: 8
Socket 1 unlocked at Level 5
Install: “Efficient I” (2 essence) - slight speed boost

Mid Game (Levels 11-30)

Iron Sword Relic

Essence Capacity: 12
Socket 2 unlocked at Level 15
Install: “Keen Edge” (4 essence) - damage boost
Install: “Vampiric Strike” (5 essence) - lifesteal on hit
Total: 9/12 essence used

Late Game (Levels 31-50)

Diamond Pickaxe Relic

Essence Capacity: 15
Socket 3 unlocked at Level 30
Install: “Fortune Glyph” (5 essence) - fortune boost
Install: “Vein Miner” (6 essence) - breaks ore veins
Install: “Auto-Smelt” (3 essence) - smelts ores
Total: 14/15 essence used

End Game (Level 50+)

Netherite Sword Relic

Essence Capacity: 20
Socket 4 unlocked at Level 50
Install: “Mythic Strike” (8 essence) - massive damage boost
Install: “Lifesteal Aura” (6 essence) - healing on hit
Install: “Chain Lightning” (5 essence) - AoE on crit
Total: 19/20 essence used
Legendary status achieved

Open Questions / Decisions Needed

Inscription Acquisition: Which methods should be default? All configurable?
Inscription Removal:
- Free to swap?
- Cost resources?
- Destroy inscription on removal?
- Cooldown period?
Relic Catalyst:
- Single-use consumable?
- Repeatable with cooldown?
- Different catalysts for different item types?
Multiple Relics:
- Can players have multiple relics?
- Shared or separate progression?
- Limit total relics?
Essence Capacity Growth:
- Static based on material?
- Increase with levels?
- Upgrade through special items?
Relic Transfer:
- Can relics be traded?
- Do they keep progression?
- Bind to player on creation?
Death Penalties:
- Lose Renown on death?
- Inscriptions damaged/lost?
- Relics indestructible?

Future Expansion Ideas

Relic Sets

Multiple relics that synergize:

“Miner’s Set” - pickaxe + helmet bonuses
Set bonuses when wearing/holding multiple relics from same set

Relic Reforging

Reset relic to reallocate inscriptions:

Keep level but clear sockets
Experiment with different builds
Cost-based system

Relic Souls/Spirits

Each relic has a “spirit” personality:

Chat messages on level up
Unique particle effects
Flavor text/lore generation

Inscription Fusion

Combine multiple inscriptions to create stronger versions:

“Keen Edge I” + “Keen Edge I” = “Keen Edge II”
Unlocks at high levels

Relic Challenges

Special objectives for high-level relics:

“Break 10,000 stone blocks” unlocks special inscription
Achievement-like system for relics

Success Metrics

A successful Relic mod will:

✅ Be usable standalone without other mods
✅ Provide meaningful tool progression
✅ Offer deep customization through inscriptions
✅ Integrate seamlessly with existing Matcha! mods
✅ Work on any server type (survival, RPG, custom maps)
✅ Be fully JSON-configurable without code changes
✅ Create engaging long-term progression goals

This is a living document and will evolve as development progresses.