# Provable Games

> Using cryptography to create incorruptible and indestructible fun.

## Battle System

Summit uses the same proven combat mechanics from [Loot Survivor](/lootsurvivor/guide/battle), creating a familiar yet competitive environment where your beasts battle each other instead of adventurers.

### Combat Fundamentals

#### Turn-Based Combat

Just like in Loot Survivor, combat follows a turn-based system:

1. **Attacker Goes First** - The challenging beast attacks
2. **Defender Counter-Attacks** - If they survive, they strike back
3. **Repeat** - Continue until one beast falls

The key difference in Summit is that **both combatants are beasts**, making type advantages and upgrades even more crucial.

#### Damage Calculation

Damage in Summit follows the Loot Survivor formula with some additions:

**Base Damage Formula:**

```
Power = Beast Level × (6 - Beast Tier)
```

**Damage Modifiers:**

* **Type Advantage**: +50% damage when strong, -50% when weak
* **Attack Potions**: Each potion adds 10% bonus damage (strength)
* **Critical Hits**: Chance based on Luck stat (0% base, up to 95%)
* **Special Abilities**: Prefix/suffix bonuses when unlocked

### Type Advantage System

Summit uses the same rock-paper-scissors system from Loot Survivor:

<div
  style={{
display: "flex",
justifyContent: "center",
marginBottom: "2rem",
marginTop: "2rem"
}}
>
  <div
    style={{
  position: "relative",
  width: "350px",
  height: "300px"
}}
  >
    {/* Brute - Top */}

    <div
      style={{
    position: "absolute",
    top: "0",
    left: "50%",
    transform: "translateX(-50%)",
    textAlign: "center",
    backgroundColor: "#dc2626",
    padding: "1rem 1.5rem",
    borderRadius: "12px",
    border: "3px solid #991b1b",
    minWidth: "140px",
    boxShadow: "0 4px 12px rgba(220, 38, 38, 0.3)"
  }}
    >
      <div style={{ fontSize: "2rem", marginBottom: "0.25rem" }}>🔨</div>
      <div style={{ fontWeight: "bold", color: "#fff", fontSize: "1.1rem" }}>Brute</div>
      <div style={{ fontSize: "0.75rem", color: "#fca5a5", marginTop: "0.25rem" }}>Bludgeon</div>
    </div>

    {/* Hunter - Bottom Left */}

    <div
      style={{
    position: "absolute",
    bottom: "0",
    left: "0",
    textAlign: "center",
    backgroundColor: "#059669",
    padding: "1rem 1.5rem",
    borderRadius: "12px",
    border: "3px solid #047857",
    minWidth: "140px",
    boxShadow: "0 4px 12px rgba(5, 150, 105, 0.3)"
  }}
    >
      <div style={{ fontSize: "2rem", marginBottom: "0.25rem" }}>⚔️</div>
      <div style={{ fontWeight: "bold", color: "#fff", fontSize: "1.1rem" }}>Hunter</div>
      <div style={{ fontSize: "0.75rem", color: "#86efac", marginTop: "0.25rem" }}>Blade</div>
    </div>

    {/* Magical - Bottom Right */}

    <div
      style={{
    position: "absolute",
    bottom: "0",
    right: "0",
    textAlign: "center",
    backgroundColor: "#7c3aed",
    padding: "1rem 1.5rem",
    borderRadius: "12px",
    border: "3px solid #6d28d9",
    minWidth: "140px",
    boxShadow: "0 4px 12px rgba(124, 58, 237, 0.3)"
  }}
    >
      <div style={{ fontSize: "2rem", marginBottom: "0.25rem" }}>✨</div>
      <div style={{ fontWeight: "bold", color: "#fff", fontSize: "1.1rem" }}>Magical</div>
      <div style={{ fontSize: "0.75rem", color: "#ddd6fe", marginTop: "0.25rem" }}>Magic</div>
    </div>

    {/* Center circular arrows */}

    <svg
      style={{
    position: "absolute",
    top: "50%",
    left: "50%",
    transform: "translate(-50%, -50%)",
    width: "100px",
    height: "100px",
    pointerEvents: "none"
  }}
    >
      {/* Three arrows showing advantage flow */}

      {/* Brute to Hunter (pointing bottom left) */}

      <path d="M 50 15 L 15 75" stroke="white" strokeWidth="3" markerEnd="url(#arrowhead)" opacity="0.9" />

      {/* Hunter to Magical (pointing right) */}

      <path d="M 15 75 L 85 75" stroke="white" strokeWidth="3" markerEnd="url(#arrowhead)" opacity="0.9" />

      {/* Magical to Brute (pointing top left) */}

      <path d="M 85 75 L 50 15" stroke="white" strokeWidth="3" markerEnd="url(#arrowhead)" opacity="0.9" />

      <defs>
        <marker id="arrowhead" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
          <polygon points="0 0, 8 3, 0 6" fill="white" />
        </marker>
      </defs>
    </svg>
  </div>
</div>

**Remember:** Brute beats Hunter, Hunter beats Magical, Magical beats Brute

### Summit-Specific Combat Features

#### Multi-Beast Attacks

Summit allows you to attack with multiple beasts in sequence:

1. **Sequential Combat** - Beasts fight one at a time
2. **All Attacks in One Transaction** - Your sequence of beasts attacks in a single transaction, giving you a better chance to take the Summit
3. **Strategic Order** - Choose your beast order wisely

#### Multi-Attack with One Beast

You can attack multiple times with the same beast in a single transaction by using revival potions:

1. **Chain Attacks** - Your beast attacks, dies, revives, and attacks again
2. **Atomic Execution** - All attacks happen in one transaction, preventing the Summit holder from adding extra lives or other defensive measures between attacks
3. **Attack Potions** - Combining Attack Potions with a multi-attack applies the potions to all your attacks, making it the most effecient use of those potions
4. **Revival Cost** - Each revival costs increasing amounts of potions (1st costs 1, 2nd costs 2, etc.)
5. **Effective for Securing Summit** - This strategy is particularly powerful for overwhelming defenders

#### Extra Lives System

Defenders can have multiple lives:

* When health reaches 0, an extra life is consumed
* Beast returns to full health (base + bonus)
* Combat continues without interruption
* Beasts can have up to 4000 extra lives

#### Critical Hit Mechanics

Critical hits in Summit are determined by the Luck stat:

| Luck | Critical Chance |
| ---- | --------------- |
| 0    | 0%              |
| 1    | 10%             |
| 10   | 25%             |
| 50   | 65%             |
| 100  | 100%            |

**Critical Hit Damage**: +100% base damage

### Strategic Considerations

#### Attacking Strategy

When planning your assault:

1. **Scout the Defender** - Check their type, health, and extra lives
2. **Order Your Beasts** - Put your strongest with type advantage first
3. **Load Attack Potions** - Apply optimal amount of attack potions
4. **Time Your Strike** - Attack when defender is weakened

#### Defending Strategy

To hold the Summit longer:

1. **Maximize Health** - Feed $CORPSE tokens for bonus health (up to 2000)
2. **Stock Extra Lives** - Apply them immediately after taking Summit
3. **Choose Defensive Upgrades** - Wisdom to gain bonus levels, Luck to get critical chance, Specials to unlocks name match bonus

#### Type Matchup Planning

Since you know the defending beast's type:

* **Favorable Matchup**: +50% damage makes victory likely
* **Neutral Matchup**: Comes down to stats and potions
* **Unfavorable Matchup**: -50% damage makes victory difficult

### Battle Rewards

#### Experience Points

XP in Summit works differently than Loot Survivor:

**Attackers Gain:**

* Base: 10 XP per attack
* Attack Streak Bonus: +1 XP per consecutive attack (max +10)
* Beasts can gain up to 40 bonus levels

**Defenders Gain:**

* XP = Defeated attacker's power / 100
* Wisdom upgrade required
* Rewards successful defense

### Tips for Success

#### Know Your Enemy

* Each beast type has predictable strengths and weaknesses
* Plan your attacks around type advantages
* Consider the defender's upgrades and health

#### Resource Efficiency

* Don't waste potions on unlikely victories
* Save revival potions for coordinated attacks
* Balance upgrades amongst your strongest beasts

#### Timing is Everything

* Attack during low activity periods
* Coordinate with allies for sequential strikes
* Take advantage of weakened defenders

The battle system rewards both tactical planning and strategic resource management. Master these mechanics to dominate the Summit!


## Beast Upgrades

Summit introduces a unique upgrade system that expands upon your [Loot Survivor Beasts](/lootsurvivor/beasts), adding new strategic layers through attributes and abilities that are exclusive to Summit gameplay.

### How Upgrades Work

Your beasts can be enhanced using tokens earned from Loot Survivor gameplay:

* **Skull Tokens** - Earned when your beasts kill adventurers (1 per kill). Used to increase attributes or unlock abilities
* **Corpse Tokens** - Extracted from your dead adventurers (1 per level). Used exclusively to increase your beast's health
* **One-time upgrades** - Permanent improvements that fundamentally change how your beast performs in Summit

The key is that Summit rewards players who are active in both games - your success in Loot Survivor directly translates to more powerful beasts in Summit:

* **$SKULL Tokens** - Earned when your beasts kill adventurers (1 per kill)
* **$CORPSE Tokens** - Extracted from your dead adventurers (1 per adventurer level)
* **Beast Locking** - When an adventurer kills one of your beasts in Loot Survivor, that beast gets locked in Summit for 24 hours and cannot attack

### Attributes

#### 🎲 Luck - Critical Hit Chance

Luck increases your chance to land critical hits for massive damage.

**Cost:** 1 $Skull per level (up to 100)

**Best For:** High powered beasts focused on dealing damage

#### ⚡ Spirit - Revival Time Reduction

Spirit reduces the revival time after your beast dies, getting them back in action faster.

**Effect:**

* Each point of Spirit reduces revival time

**Revival Time Calculation:**

* Base: 24 hours
* With Maximum Spirit: Reduced by 20 hours
* Minimum possible: 4 hours

**Cost:** 1 $Skull per level (up to 100)

**Best For:** Active players who attack frequently

### Abilities

Abilities are powerful one-time unlocks that fundamentally change how your beast performs:

#### ⭐ Specials - Name Match Bonuses

Unlocks your beast's prefix and suffix abilities, providing combat bonuses based on name matches.

**Effect:**

* Activates prefix ability (8x bonus damage)
* Activates suffix ability (2x bonus damage)
* Bonuses apply when names match in combat

**Cost:** 10 Skull Tokens

**Best For:** Beasts with matching names against strong defenders

#### 🤝 Diplomacy - Shared Rewards & Power Boost

Empower and share rewards with other beasts that have the same prefix and suffix.

**Effect:**

* When a matching beast holds Summit, you gain a share of the $SURVIVOR reward
* Empowers the matching Summit holder with a damage bonus based on your beast's power
* Creates alliance opportunities
* Encourages coordinated play

**Damage Bonus Calculation:**

```
Damage Boost = (Total Power of all Diplomacy beasts / 250) × 10%
```

**Example:**

* Your "Agony Bane" beast is holding the Summit
* Two other "Agony Bane" beasts (Power 150 each) have Diplomacy unlocked
* Their Total Power = 150 + 150 = 300
* Summit holder gets: (300 / 250) × 10% = 10% damage boost
* Note: Summit holder does not get bonus from itself unlocking Diplomacy

**Cost:** 15 Skull Tokens

**Best For:**

* Players with multiple matching beasts or coordinating with allies
* Casual players who won't take Summit themselves but have name matches with powerful players

#### 🧠 Wisdom - Defensive XP Gain

Gain experience points when successfully defending attacks on the Summit.

**Effect:**

* XP gained = Attacker's power / 100
* Only triggers on successful defense
* Helps level up while holding Summit

**Cost:** 20 Skull Tokens

**Best For:** Defensive strategies and long Summit reigns

### Vitality - Bonus Health

#### ❤️ Health Enhancement

Permanently increase your beast's health using Corpse Tokens.

**Stats:**

* Maximum Bonus: 2,000 health
* Cost: 1 Corpse Token per health point

**Strategic Impact:**

* More health = longer Summit defense
* Essential for tanky builds
* Pairs well with Extra Life potions

### Upgrade Strategy Guide

#### Offensive Build

Focus on maximizing damage output over time:

1. **Luck** to gain critical chance
2. **Specials** for name bonuses
3. **Spirit** for frequent attacks

#### Defensive Build

Optimize for holding the Summit:

1. **Maximum health** (2,000 bonus)
2. **Wisdom** for XP while defending
3. **Moderate Luck** for counter-attacks

#### Alliance Build

For coordinated groups:

1. **Diplomacy** on matching beasts
2. **Balanced stats** across team
3. **Coordinate Summit control**

### Token Management

#### Earning Tokens

Tokens are earned through [Loot Survivor](/lootsurvivor) gameplay:

##### Skull Tokens

Earned when your beast successfully kills an adventurer:

* **1 Skull Token** per adventurer killed
* Accumulates across all your beasts

##### Corpse Tokens

Extracted from your own dead adventurers:

* **1 Corpse Token per adventurer level**
* Only from adventurers you own
* Adventurer must be dead (0 health)
* Extract tokens through the Summit interface

**Example:** A dead level 15 adventurer yields 15 Corpse Tokens

#### Spending Priority

Consider these factors:

1. **Immediate needs** - What helps you win now?
2. **Long-term goals** - Building for sustained success
3. **Beast potential** - Invest in your strongest beasts
4. **Play style** - Match upgrades to how you play

The upgrade system transforms your beasts into customized warriors. Choose wisely - these permanent improvements define your Summit strategy!

### What Happens After Summit Ends?

There are currently no planned expansions or additional seasons of Summit beyond the current game. Summit is a finite experience — once the reward pool is distributed, the game concludes.

**Will upgrades persist if another Summit happens?**

If a future Summit is introduced, our intention is to carry over beast upgrades and stats. However, we cannot guarantee this, as it depends on factors that are not yet known — including game design decisions, technical considerations, and the needs of future player bases.

Our commitment is to build valuable and fun experiences. We will not compromise future gameplay, as it would be -EV for everyone in the ecosystem. What we can say is that the upgrades you earn in this Summit are designed for this Summit — to help you compete, complete quests, and earn $SURVIVOR.

**The right mindset:** Upgrade your beasts for the game in front of you. Every $SKULL and $CORPSE you spend should be an investment in winning now — holding the Summit longer, completing more quests, and claiming your share of the 92,000 $SURVIVOR reward pool (56,000 Summit, 36,000 quests) plus 8,000 $SURVIVOR seeded as initial consumable liquidity.


## Consumables

Potions are the strategic fuel of Summit battles. Knowing when and how to use them can mean the difference between a brief appearance and a legendary reign.

### Types of Potions

#### 🔄 Revival Potions

Skip the 24-hour death cooldown and get back in the fight immediately.

**How They Work:**

* Instantly revives a dead beast
* Cost increases with each use on the same beast
* Essential for chain attacks

**Cost Scaling:**

| Revival # | Potions Required | Total Used |
| --------- | ---------------- | ---------- |
| 1st       | 1                | 1          |
| 2nd       | 2                | 3          |
| 3rd       | 3                | 6          |
| 4th       | 4                | 10         |
| ...       | ...              | ...        |
| 64th      | 64               | 904        |

**Note:** Revival cost caps at 64 potions. All revivals will cost 64 potions at this point.

**Strategic Uses:**

* Enable rapid counter-attacks after defeat
* Chain multiple beast assaults
* Maintain pressure on Summit holder
* React quickly to opportunities
* Combine with attack potions in a multi-attack

#### ⚔️ Attack Potions

Boost your damage output for devastating first strikes.

**How They Work:**

* Each potion increases attack damage
* Only usable by attackers (not defenders)
* Maximum 255 potions per beast

**Strategic Uses:**

* Overwhelm high-health defenders
* Secure one-shot kills with type advantage
* Break through extra lives quickly
* Make impossible matchups winnable

#### ❤️ Extra Life Potions

Give your beast multiple chances to defend the Summit.

**How They Work:**

* Automatically activates when health reaches 0
* Restores beast to full health (base + bonus)
* Can only be applied to current Summit holder
* Maximum 4000 extra lives

**Strategic Uses:**

* Extend Summit defense duration
* Discourage attackers (psychological warfare)
* Survive coordinated assaults

#### ☠️ Poison Potions

Slowly weaken the Summit holder over time without direct combat.

**How They Work:**

* Deals 1 damage per second to the Summit holder
* Damage stops at 1 health and 0 extra lives (cannot kill)
* Multiple poison potions stack for faster damage
* Can only be applied to current Summit holder

**Strategic Uses:**

* Weaken defenders before attacking
* Force defenders to waste extra lives
* Create time pressure on Summit holders
* Coordinate with allies for timed strikes

### Potion Market

#### Continuous Clearing Auction (CCA)

Potions are distributed using a Continuous Clearing Auction (CCA) — the same mechanism used for [Loot Survivor's dungeon tickets](/lootsurvivor/dungeon-tickets). Potions are the revenue source of Summit.

**How It Works:**

* Potions are streamed block-by-block into an [Ekubo](https://ekubo.org/) TWAMM (Time-Weighted Average Market Maker) pool
* Price starts intentionally high at game launch and decreases over time as supply enters the pool
* The price naturally settles at what players are willing to pay -no more, no less
* At launch, each of the four potion pools is seeded with **2,000 $SURVIVOR** in initial liquidity for price discovery and stability.

**Daily Issuance Rates:**

| Potion Type   | Tokens Per Day | Initial Liquidity | Starting Price |
| ------------- | -------------- | ----------------- | -------------- |
| ⚔️ Attack     | 97,206         | 2,000 $SURVIVOR   | $0.01          |
| 🔄 Revival    | 97,206         | 2,000 $SURVIVOR   | $0.01          |
| ☠️ Poison     | 97,206         | 2,000 $SURVIVOR   | $0.01          |
| ❤️ Extra Life | 4,860          | 2,000 $SURVIVOR   | $0.20          |

**Key Features:**

* Price adjusts based on supply and demand in real time
* Current price is always visible before purchase
* Purchase with any token on Starknet

**Strategic Purchasing:**

* No need to rush — prices start high and come down as potions stream in
* Monitor price trends for optimal buying times
* Consider DCA (Dollar-Cost Averaging) orders for bulk purchases

**Revenue Distribution:**
100% of proceeds from potion sales are used to buy back $SURVIVOR tokens for the DAO treasury, supporting the long-term sustainability of the Survivor ecosystem.

### Tips for Success

#### For Beginners

1. Start with revival potions to learn timing
2. Use attack potions with type advantage
3. Apply extra lives on attack before taking Summit

#### For Veterans

1. Calculate exact potion requirements
2. Time market purchases strategically
3. Coordinate group strategies
4. Optimize cost per second held

#### Common Mistakes

* Using attack potions with type disadvantage
* Applying extra lives on weak beasts
* Reviving the same beast too many times
* Ignoring potion economics

The key to potion mastery is understanding not just what each does, but when each creates maximum value. Use them wisely, and the Summit will be yours!

### After Summit Ends

Potions are consumables designed exclusively for Summit gameplay. Once the game concludes and the reward pool is fully distributed, potions will have no further use case. Purchase and use them with this in mind — they are a tool for winning now, not an asset to hold.


## Disclaimers

This documentation is provided for informational purposes only and is not legal, financial, tax, or investment advice. You are responsible for understanding and complying with all applicable laws, rules, and regulations in your jurisdiction.

### Smart Contract Risk (Unaudited)

Summit is powered by smart contracts. **These smart contracts are unaudited** and may contain bugs, design flaws, or security vulnerabilities. Smart contracts and blockchain systems can fail unexpectedly, be exploited, or behave in ways that cause partial or total loss of funds, tokens, in-game items, or other assets.

### No Warranties (As-Is, As-Available)

Summit and all related software, smart contracts, interfaces, and documentation are provided on an **“AS IS”** and **“AS AVAILABLE”** basis, without warranties of any kind (express, implied, or statutory), including warranties of merchantability, fitness for a particular purpose, non-infringement, or that the system will be uninterrupted, secure, error-free, or free of harmful components.

### Assumption of Risk; Irreversible Transactions

By interacting with Summit, you acknowledge and accept the risks of cryptographic and blockchain-based systems, including volatility, MEV/front-running, downtime, congestion, reorgs, forks, bridge failures, oracle or pricing anomalies, and wallet compromise. Blockchain transactions are typically **irreversible** once confirmed, and neither the Summit team nor any contributors can reverse, cancel, or recover transactions or assets.

### Third-Party Dependencies

Summit may integrate with or rely on third-party protocols, networks, wallets, RPC providers, bridges, liquidity venues, and other services. Those third parties are not under our control, and failures or changes in third-party services may result in loss of assets, degraded functionality, incorrect displays of information, or inability to access features.

### Limitation of Liability

To the fullest extent permitted by law, in no event will the Summit team, contributors, or any related parties be liable for any indirect, incidental, special, consequential, exemplary, or punitive damages, or for any loss of profits, revenue, goodwill, data, or assets, arising out of or related to your access to or use of Summit, the smart contracts, or any related services, even if advised of the possibility of such damages.

### Your Responsibility

You are solely responsible for safeguarding your wallet, private keys, and recovery phrases, verifying addresses and transaction parameters, and understanding the mechanics of any smart contract interactions before you approve them. You are also solely responsible for any taxes arising from your activity.


## Summit: FAQ

Find answers to common questions about Summit. Summit is currently in alpha and details may change.

### General

**What is Summit?**

Summit is an all-against-all, king-of-the-hill PvP arena where players use Loot Survivor Beasts to battle for control of the Summit and earn $SURVIVOR rewards.

**Is Summit still in alpha?**

Yes. Summit is currently in alpha. Game mechanics, rewards, and features are subject to change.

**How long does a Summit game last?**

Each Summit game lasts 8 million seconds (approximately 93 days).

**What is the total reward pool?**

92,000 $SURVIVOR total: 56,000 for holding the Summit and 36,000 for quest completion, plus 8,000 $SURVIVOR seeded as initial liquidity for the four consumables at launch.

### Getting Started

**What do I need to play?**

You need Beasts from Loot Survivor. Beasts are earned by killing monsters during Loot Survivor gameplay or can be purchased on secondary markets.

**How do I get Beasts?**

Play Loot Survivor and kill beasts during your adventure — each beast kill mints a collectible Beast. You can also buy them on secondary markets.

**How do I start?**

Select one of your Beasts and attack the current Summit holder. Your first attack unlocks quests for that beast.

### Battle System

**How do battles work?**

Battles are turn-based: the attacker strikes first, then the defender counter-attacks. Damage is calculated using Base Power = Beast Level x (6 - Beast Tier), modified by type advantages and upgrades.

**What are the type advantages?**

Rock-paper-scissors system: Brute beats Hunter, Hunter beats Magical, Magical beats Brute. Having type advantage gives +50% damage; disadvantage gives -50% damage.

**What is multi-attack?**

You can attack the Summit multiple times in a single transaction using revival potions. The cost increases per use (1st costs 1 potion, 2nd costs 2, etc., up to a max cost of 64). All attacks happen atomically, preventing the defender from making changes mid-battle.

**How do critical hits work?**

Critical hits deal +100% base damage. The chance depends on your beast's Luck stat, ranging from 0% at Luck 0 to 100% at Luck 100.

**How does XP work?**

Attackers earn 10 XP base + 1 XP per consecutive attack (max +10 bonus). Attackers can gain up to 40 bonus levels. Defenders earn XP only if they have the Wisdom upgrade (XP = attacker's power / 100).

### Beast Upgrades

**What are $SKULL and $CORPSE tokens?**

$SKULL tokens are earned by killing beasts in Loot Survivor (1 per kill) and used for attribute and ability upgrades. $CORPSE tokens are earned from dead adventurers in Loot Survivor (1 per adventurer level) and used for health upgrades.

**What attributes can I upgrade?**

* **Luck**: 1 $SKULL per level (up to 100 levels). Increases critical hit chance.
* **Spirit**: 1 $SKULL per level (up to 100 levels). Reduces revival cooldown from 24 hours down to 4 hours at max level.

**What abilities can I unlock?**

* **Specials** (10 $SKULL): Activates prefix (8x) and suffix (2x) damage bonuses when beast names match.
* **Diplomacy** (15 $SKULL): Share rewards with other beasts that have matching names.
* **Wisdom** (20 $SKULL): Gain XP when defending (XP = attacker power / 100).
* **Vitality** (1 $CORPSE per point): Add bonus health, up to 2,000 extra HP.

### Consumables

**What potions are available?**

* **Revival Potions**: Skip the 24-hour death cooldown. Cost increases per use (1, 2, 3... up to 64).
* **Attack Potions**: +10% bonus damage per potion (max 255 per beast). Attackers only.
* **Extra Life Potions**: Give defenders multiple lives (max 4,000). Restores full health when consumed.
* **Poison Potions**: Deal 1 damage per second to the Summit holder. Multiple stack. Cannot kill (stops at 1 HP with 0 extra lives).

**How does the potion market work?**

Potions are sold through a Continuous Clearing Auction (CCA) via Ekubo liquidity pool. Prices start high and decrease over time. 100% of proceeds go to buy back $SURVIVOR for the DAO treasury.

### Rewards & Quests

**How do I earn $SURVIVOR from holding the Summit?**

The Summit holder earns 0.007 $SURVIVOR per second. You must hold for at least one full block (approximately 2-3 seconds) to earn anything. Rewards are claimed when your beast is dethroned.

**How does Diplomacy reward sharing work?**

Each beast with the Diplomacy upgrade and a matching name earns 0.00005 $SURVIVOR per second while a matching beast holds the Summit. Up to 75 matching beasts can earn simultaneously.

**What quests are available?**

Quests include: First Blood (attack the Summit), Consistency is Key (10-attack streak), level-up milestones (1/3/5/10 levels), Summit Conqueror (capture the Summit), Iron Grip (hold for 10+ seconds), Second Wind (revive and attack), and A Vital Boost (use attack potion). Each beast can earn up to 0.95 $SURVIVOR from quests. The 36,000 $SURVIVOR quest pool is first come, first serve.

### Strategy

**How should I choose which beast to use?**

Check the current Summit holder's type. Use a beast with type advantage for +50% damage. Higher level and lower tier beasts deal more base damage.

**When is the best time to attack?**

Attack during low-activity periods or when top beasts are on cooldown (24 hours after death, reduced by Spirit upgrades). Early in the game, there are fewer beasts competing and lower upgrade costs.

**Should I focus on offense or defense?**

Offensive builds (Attack Potions, Luck for crits) are good for capturing the Summit. Defensive builds (Extra Lives, Vitality) help hold it longer to earn more $SURVIVOR per second.

### After the Game Ends

**Will there be another Summit season?**

There are no planned additional seasons at this time.

**Do my beast upgrades carry over?**

Upgrades are designed for the current Summit. While upgrades may carry over to future events, this is not guaranteed.


## Savage Summit

Savage Summit is an all-against-all, king-of-the-hill battle game where players use their [Loot Survivor Beasts](/lootsurvivor/beasts) to fight for control of the Summit. The beast standing on the Summit earns rewards based on how long they can defend their position.

### How It Works

Summit takes the collectible beasts from Loot Survivor and gives them a new battlefield where they can compete directly against each other. Think of it as a PvP arena where your beasts battle for supremacy and earn rewards.

#### The Basic Loop

1. **Challenge the Summit** - Use your beasts to attack whoever currently holds the Summit
2. **Claim Victory** - If your beast wins, it becomes the new king of the hill
3. **Defend Your Throne** - Fight off challengers to maintain control
4. **Earn Rewards** - Receive 0.007 $SURVIVOR for every second you hold the Summit

#### What You Need to Play

* **Beast NFTs**
  * Collect them by playing [Loot Survivor](https://lootsurvivor.io/survivor)
  * Purchase on marketplace: [Marketplace](https://beast-dex.vercel.app/marketplace)

### Key Features

#### 🏆 King of the Hill

Only one beast can control the Summit at a time. Every attacker tries to dethrone the current king, creating an endless battle for dominance.

#### 💀 Revival Mechanics

Dead beasts have a 24-hour cooldown before they can fight again - unless you use revival potions to get them back in action immediately.

#### 📈 Beast Progression

Your beasts gain experience from battles and can be upgraded with new abilities unique to Summit:

* **Luck** - Increases critical hit chance
* **Spirit** - Reduces revival cooldown time
* **Specials** - Unlocks prefix/suffix name match bonus
* **Diplomacy** - Empower & Share rewards with matching beasts
* **Wisdom** - Gain XP when defending the Summit
* **Vitality** - Gain Bonus Health

#### 📜 Quests

Complete [objectives](/summit/quests) with your beasts to earn $SURVIVOR without holding the Summit:

* **10 quests** ranging from first attacks to holding the Summit for 10+ seconds
* **Per-beast tracking** — each beast has independent quest progress
* **First come, first serve** — 36,000 $SURVIVOR quest pool depletes as players complete quests

#### 🧪 Consumables

Four types of potions add layers of strategy:

* **Revival Potions** - Skip the death cooldown
* **Attack Potions** - Boost damage for assault
* **Extra Life Potions** - Give defenders multiple lives
* **Poison Potions** - Poison the Summit, making it take damage every second

### Game Ending

Summit reward allocation is split as follows:

* **56,000 $SURVIVOR** for holding the Summit
* **36,000 $SURVIVOR** in the quest pool for completing [quests](/summit/quests)
* **8,000 $SURVIVOR** seeded as initial liquidity across the Attack, Revival, Poison, and Extra Life potion pools
* Game ends after 8 million seconds (93 days)

### Mainnet Contracts

| Contract          | Address                                                                                                                                                                    |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Summit Game       | [`0x0214d382e80781f8c1059a751563d6b46e717c652bb670bf230e8a64a68e6064`](https://voyager.online/contract/0x0214d382e80781f8c1059a751563d6b46e717c652bb670bf230e8a64a68e6064) |
| Attack Potion     | [`0x016f9def00daef9f1874dd932b081096f50aec2fe61df31a81bc5707a7522443`](https://voyager.online/contract/0x016f9def00daef9f1874dd932b081096f50aec2fe61df31a81bc5707a7522443) |
| Poison Potion     | [`0x049eaed2a1bA2F2Eb6Ac2661ffd2d79231CdD7d5293D9448Df49c5986C9897aE`](https://voyager.online/contract/0x049eaed2a1bA2F2Eb6Ac2661ffd2d79231CdD7d5293D9448Df49c5986C9897aE) |
| Revive Potion     | [`0x029023e0a455d19d6887bc13727356070089527b79e6feb562ffe1afd6711dbe`](https://voyager.online/contract/0x029023e0a455d19d6887bc13727356070089527b79e6feb562ffe1afd6711dbe) |
| Extra Life Potion | [`0x016dea82a6588ca9fb7200125fa05631b1c1735a313e24afe9c90301e441a796`](https://voyager.online/contract/0x016dea82a6588ca9fb7200125fa05631b1c1735a313e24afe9c90301e441a796) |
| Corpse Token      | [`0x0103eafe79f8631932530cc687dfcdeb013c883a82619ebf81be393e2953a87a`](https://voyager.online/contract/0x0103eafe79f8631932530cc687dfcdeb013c883a82619ebf81be393e2953a87a) |
| Skull Token       | [`0x01c3c8284d7EED443b42F47e764032a56eAf50A9079D67993B633930E3689814`](https://voyager.online/contract/0x01c3c8284d7EED443b42F47e764032a56eAf50A9079D67993B633930E3689814) |

See [Disclaimers](/summit/disclaimers) for important legal and smart contract risk information, including the fact that Summit contracts are unaudited.

### Getting Started

1. **Get Beasts** - Own at least one beast NFT
2. **Scout the Summit** - Check who currently holds the position
3. **Plan Your Attack** - Time your assault when you have the best chance
4. **Upgrade Wisely** - Use **$SKULL** tokens earned from killing adventurers and **$CORPSE** tokens
   earned from fallen adventurers to upgrade your beasts
5. **Complete [Quests](/summit/quests)** - Complete objectives for your beasts to earn $SURVIVOR

### Why Play Summit?

* **Direct Competition** - Test your beasts against other players
* **Earn Rewards** - $SURVIVOR tokens for holding the Summit and completing [quests](/summit/quests)
* **Strategic Depth** - Multiple paths to victory through upgrades and timing
* **Community Interaction** - Form alliances or rivalries with other players
* **Limited Duration** - Once the time is up and rewards distributed, the game ends

Ready to conquer the Summit? Learn about the [Battle System](/summit/battle-system) to understand combat mechanics, or check out the [Quests](/summit/quests) to start earning rewards right away.


## Quests Guide

Complete objectives with your beasts to earn $SURVIVOR tokens from the quest reward pool. Quests provide a structured way to earn rewards beyond holding the Summit, rewarding players for engaging with all aspects of the game.

### Reward Pool

Quests draw from a dedicated pool of **36,000 $SURVIVOR** tokens:

* Each beast can earn up to **0.95 $SURVIVOR** by completing all quests
* The pool is **first come, first serve** — once depleted, quests no longer reward tokens
* Quest rewards are separate from Summit holding rewards

### Quest List

| Quest              | Description                                       | Reward ($SURVIVOR) | Notes                    |
| ------------------ | ------------------------------------------------- | ------------------ | ------------------------ |
| First Blood        | Attack the Summit                                 | 0.05               | Unlocks all other quests |
| Consistency is Key | Reach a max attack streak of 10                   | 0.10               |                          |
| Growing Stronger   | Level up once                                     | 0.04               | Level Up Tier 1          |
| Rising Power       | Level up 3 times                                  | 0.06               | Level Up Tier 2          |
| Apex Predator      | Level up 5 times                                  | 0.08               | Level Up Tier 3          |
| Mastery            | Level up 10 times                                 | 0.12               | Level Up Tier 4          |
| Summit Conqueror   | Capture the Summit                                | 0.10               |                          |
| Iron Grip          | Hold the Summit for 10+ seconds                   | 0.20               | Highest reward           |
| Second Wind        | Buy a revival potion and attack with a dead beast | 0.10               |                          |
| A Vital Boost      | Buy an attack potion and attack using it          | 0.10               |                          |

### Key Mechanics

#### Per-Beast Tracking

Quests are tracked **per beast** — each beast has its own independent quest progress. This means you can earn quest rewards across multiple beasts.

#### Tiered Level Up Quests

The level up quests have 4 progressive tiers with increasing rewards:

1. **Growing Stronger** (1 level) → 0.04 $SURVIVOR
2. **Rising Power** (3 levels) → 0.06 $SURVIVOR
3. **Apex Predator** (5 levels) → 0.08 $SURVIVOR
4. **Mastery** (10 levels) → 0.12 $SURVIVOR

Each tier is a separate quest — completing higher tiers also completes the lower ones.

#### In-Game Quest Guides

Some quests have built-in help guides accessible via the help button in the quests modal. These provide step-by-step instructions for completion.

### Tips for Success

#### Getting Started

1. **Check your quest progress** in the quests modal to see what's available
2. **Check your beasts** by hovering over the beast cards to see what's remaining

#### Maximizing Rewards

1. **Prioritize Iron Grip** — at 0.20 $SURVIVOR, it's the highest single quest reward
2. **Level up tiers stack** — working toward Mastery (10 levels) completes all four level up quests for a combined 0.30 $SURVIVOR
3. **Spread across beasts** — since quests are per-beast, completing quests on multiple beasts multiplies your total earnings

#### Act Fast

The quest reward pool is finite and first come, first serve. Early and active players will claim the largest share of the 36,000 $SURVIVOR pool before it's depleted.


## Rewards Guide

Summit's reward system is straightforward: hold the Summit longer, earn more $SURVIVOR. With a total gameplay pool of **92,000 $SURVIVOR** (plus initial liquidity noted below) to distribute, every second matters.

### How Rewards Work

#### The Prize Pool

Summit has a **finite reward pool**:

* **Total Distribution**: 92,000 $SURVIVOR tokens
* **Summit Holding**: 56,000 $SURVIVOR - distributed to holding the Summit
* **Quest Rewards**: 36,000 $SURVIVOR - distributed through quest completions
* **Initial Potion Liquidity**: 8,000 $SURVIVOR seeded across the 4 consumable pools at launch
* **Rate**: \~0.007 $SURVIVOR per second to the Summit holder
* **Game Duration**: 8 million seconds (93 days)

#### Block-by-Block Earnings

Every block your beast holds the Summit:

* Base reward: **\~0.007 $SURVIVOR** per second
* Reward accumulates automatically
* Can be claimed when your beast is dethroned
* **Your beast must hold the Summit for at least one full block to earn any reward.**

**Examples (blocks are \~2-3 seconds):**

| Scenario                                                   | Reward                                                         |
| ---------------------------------------------------------- | -------------------------------------------------------------- |
| Beast claims Summit and is dethroned in the **same block** | **0 $SURVIVOR** — no full block held                           |
| Beast claims Summit and holds for **1 block** (\~2-3s)     | **\~0.014-0.021 $SURVIVOR** — rewarded for time between blocks |
| Beast holds for **10 blocks** (\~20-30s)                   | **\~0.07-0.105 $SURVIVOR**                                     |

**Diplomacy Reward Sharing:**

If matching beasts have the Diplomacy upgrade:

* Each Diplomacy beast receives **0.00005 $SURVIVOR per second**
* Maximum of 75 matching beasts can exist
* Summit holder keeps the remainder

**Example Distribution Each Second:**

| Diplomacy Beasts | Each Gets | Summit Holder Gets |
| ---------------- | --------- | ------------------ |
| 0                | -         | 0.007 $SURVIVOR    |
| 10               | 0.00005   | 0.0065 $SURVIVOR   |
| 75 (max)         | 0.00005   | 0.00325 $SURVIVOR  |

\*$SURVIVOR is the governance token for the Survivor ecosystem

### The Economics of Summit

#### Circular Economy

Summit creates a sustainable economic loop:

1. **Potion Market Revenue** → 100% used to buy back $SURVIVOR tokens
2. **$SURVIVOR Distribution** → Tokens distributed to Summit holders
3. **Governance Power** → Token holders govern the ecosystem
4. **Market Dynamics** → Demand for potions driven by competition for $SURVIVOR

**Fair Distribution:**

* No pre-mining or special allocations
* Pure merit-based rewards
* Skill and strategy determine earnings
* Self-sustaining through potion sales

### Maximizing Your Rewards

#### Timing Strategies

**Early Bird Advantage:**

* Fewer beasts in circulation early on = less competition
* Lower skull token supply = fewer upgraded beasts
* Establish dominance before the ecosystem matures

**Peak Hours vs Off-Hours:**

* Monitor global activity patterns
* Strike during low-competition periods
* Coordinate with timezone advantages

**Beast Cooldown Windows:**

* Track when dominant beasts are on revival cooldown
* Attack when top competitors can't respond
* Monitor recent battles to predict cooldown timings
* 24-hour windows create predictable opportunities

**Potion Supply Awareness:**

* Monitor current potion market supply
* Stock up when prices drop during low demand
* Scarcity creates defensive advantages

### Tracking Your Performance

#### Key Metrics

Monitor these statistics:

* **Total $SURVIVOR Earned**: Your lifetime rewards
* **Seconds Held**: Total time on Summit
* **ROI**: Earnings vs investment

#### Alliance Opportunities

**Strategic Cooperation:**

* Diplomacy creates passive income for supporters (see reward distribution above)
* Coordinate attacks with name-matching beast owners
* Share upgrade costs and potion resources
* Build "beast families" for mutual benefit

### Summary

Summit's reward system is elegant in its simplicity: defend the hill, earn $SURVIVOR. With 92,000 $SURVIVOR to distribute — 56,000 for holding the Summit, 36,000 for quest rewards, and 8,000 seeded as initial potion liquidity — success comes down to:

1. **Strategic Timing** - Attack when you can win and hold
2. **Quests Completion** - Focus on completing as many quests as possible
3. **Resource Management** - Invest enough to succeed, not more
4. **Beast Development** - Build defensive capabilities
5. **Governance Value** - $SURVIVOR tokens grant voting power in the Survivor ecosystem

The clock is ticking, the reward pool is finite, and only the strongest beasts will claim the largest shares. Make every second count!


## Combat Mechanics

Combat in Loot Survivor involves complex calculations that determine damage output between adventurers and beasts. Understanding these mechanics helps you optimize your build and strategy.

### Combat Overview

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '2rem 0' }}>
  <div style={{ marginBottom: '1rem' }}>
    Combat damage is calculated through a series of steps:
  </div>

  1. **Base Damage Calculation** - Weapon tier and level determine base power
  2. **Elemental Adjustments** - Type advantages modify damage by ±50%
  3. **Bonus Calculations** - All bonuses use elemental adjusted damage:
     * **Strength Bonus** - +10% of elemental damage per STR point
     * **Critical Hit Bonus** - +100% of elemental damage (if triggered)
     * **Special Bonuses** - Name matches (2× or 8× elemental damage)
  4. **Total Attack** - Sum of elemental damage + all bonuses
  5. **Armor Reduction** - Base armor (tier × level) subtracted from total
  6. **Minimum Damage** - Adventurers deal min 4, beasts deal min 2
</div>

### Damage Calculation Formula

<div style={{ background: '#0a0a0a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #333', margin: '2rem 0' }}>
  #### Step 1: Base Attack & Defense

  ```
  Base Attack = Item Level × (6 - Tier)
  Base Defense = Armor Level × (6 - Tier)
  ```

  **Tier Damage Formula:**

  | Tier   | Formula (6 - Tier)    | Example (Level 10) |
  | ------ | --------------------- | ------------------ |
  | **T1** | 10 × (6 - 1) = 10 × 5 | 50 damage          |
  | **T2** | 10 × (6 - 2) = 10 × 4 | 40 damage          |
  | **T3** | 10 × (6 - 3) = 10 × 3 | 30 damage          |
  | **T4** | 10 × (6 - 4) = 10 × 2 | 20 damage          |
  | **T5** | 10 × (6 - 5) = 10 × 1 | 10 damage          |

  #### Step 2: Elemental Adjustment

  ```
  Elemental Effect = Base Attack / 2
  ```

  * **Strong** (Type advantage): `Base Attack + Elemental Effect` (+50% damage)
  * **Fair** (Neutral): `Base Attack` (no change)
  * **Weak** (Type disadvantage): `Base Attack - Elemental Effect` (-50% damage)

  #### Step 3: Add Bonuses (All Based on Elemental Adjusted Damage)

  ```
  Strength Bonus = (Elemental Adjusted Damage × STR) / 10
  Critical Bonus = Elemental Adjusted Damage × 1.0 (if triggered)
  Special Bonus = Elemental Adjusted Damage × Multiplier (if name match)

  Total Attack = Elemental Adjusted Damage + Strength Bonus + Critical Bonus + Special Bonus
  ```

  #### Step 4: Apply Armor & Calculate Final Damage

  ```
  Base Armor = Armor Level × (6 - Tier)
  Final Damage = MAX(Minimum Damage, Total Attack - Base Armor)

  Minimum Damage:
  - Adventurer attacks: 4 damage
  - Beast attacks: 2 damage
  ```
</div>

### Combat Type System

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '1rem 0' }}>
  #### The Three Combat Types

  | Combat Type | Weapon   | Armor | Strong Against | Weak Against |
  | ----------- | -------- | ----- | -------------- | ------------ |
  | **Brute**   | Bludgeon | Metal | Hunter         | Magical      |
  | **Hunter**  | Blade    | Hide  | Magical        | Brute        |
  | **Magical** | Magic    | Cloth | Brute          | Hunter       |

  #### Type Advantage Cycle

  ```
  Brute → Hunter → Magical → Brute
  ```

  * **Brute** (Bludgeon + Metal) beats **Hunter** (Blade + Hide)
  * **Hunter** (Blade + Hide) beats **Magical** (Magic + Cloth)
  * **Magical** (Magic + Cloth) beats **Brute** (Bludgeon + Metal)

  > **Combat Rule:** Type advantage grants +50% damage, disadvantage gives -50% damage
</div>

### Critical Hits

<div style={{ background: '#2a1a3e', padding: '1.5rem', borderRadius: '8px', border: '1px solid #a855f7', margin: '1rem 0' }}>
  Critical hits provide bonus damage based on your LUCK stat:

  #### Critical Hit Chance

  ```
  Crit Chance = LUCK / 100 (%)
  ```

  | LUCK | Crit Chance |
  | ---- | ----------- |
  | 0    | 0%          |
  | 25   | 25%         |
  | 50   | 50%         |
  | 75   | 75%         |
  | 100  | 100%        |

  #### Critical Hit Damage

  When a critical hit occurs, bonus damage is added:

  * **Critical bonus:** +100% of elemental-adjusted damage
  * **Total damage:** 2× the normal damage when a critical hit is rolled
</div>

### Name Match Bonuses

<div style={{ background: '#2a2a1a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #10b981', margin: '1rem 0' }}>
  High-level beasts (19+) and items (Greatness 19+) have special name prefixes that provide combat bonuses when matched.

  #### Name Structure

  <div style={{ marginBottom: '1rem' }}>
    Items and beasts can have names like "**Whisper** **Glow** Demon" where:
  </div>

  * **Prefix 1:** "Whisper" (primary name)
  * **Prefix 2:** "Glow" (secondary name)

  #### Bonus Calculation

  | Match Type         | Damage Multiplier      |
  | ------------------ | ---------------------- |
  | **Prefix 2 Match** | 2× elemental damage    |
  | **Prefix 1 Match** | 8× elemental damage    |
  | **Both Match**     | Cumulative (16× total) |

  #### Important Note

  * **Offense**: If your weapon shares a prefix with a beast, you deal bonus damage.
  * **Defense**: If your **armor** shares a prefix with a beast, the beast deals bonus damage to you.

  > **Pro Tip:** Name matches are a double-edged sword—gear that empowers you against some beasts might leave you vulnerable to others!
</div>

### Strength Bonus

<div style={{ background: '#1a1a1a', padding: '1rem', borderRadius: '8px', margin: '1rem 0' }}>
  The Strength stat provides a direct damage increase:

  ```
  Strength Bonus = (Elemental Adjusted Damage × STR) / 10
  ```

  | STR | Damage Increase |
  | --- | --------------- |
  | 0   | +0%             |
  | 5   | +50%            |
  | 10  | +100%           |
  | 15  | +150%           |
  | 20  | +200%           |
</div>

### Combat Example

<div style={{ background: '#0a0a0a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #333', margin: '1rem 0' }}>
  **Scenario:** Level 10 Adventurer with T3 Blade attacking a Beast with T4 Hide armor

  ```
  1. Base Attack = 10 (level) × (6 - 3) = 10 × 3 = 30
  2. Elemental: Blade vs Hide = Fair (no change) = 30
  3. Bonuses (all based on elemental damage of 30):
     - Strength Bonus (STR=5): 30 × 0.5 = +15
     - Critical Hit: None triggered
     - Special Bonus: None
  4. Total Attack = 30 + 15 = 45

  5. Base Armor = 10 (level) × (6 - 4) = 10 × 2 = 20
  6. Final Damage = MAX(4, 45 - 20) = 25 HP
  ```

  **Alternative with Type Advantage & Critical:**

  ```
  If using T3 Bludgeon vs Hide (Strong) with critical hit:
  1. Base Attack = 30
  2. Elemental: 30 + (30/2) = 45 (+50% for type advantage)
  3. Bonuses (all based on elemental damage of 45):
     - Strength (STR=5): 45 × 0.5 = +22
     - Critical Hit: 45 × 1.0 = +45
     - Special: None
  4. Total Attack = 45 + 22 + 45 = 112

  5. Base Armor = 20
  6. Final Damage = MAX(4, 112 - 20) = 92 HP!
  ```

  **Ultimate Example with Name Match:**

  ```
  T3 Bludgeon "Glow" vs Beast "Glow" (Prefix 2 match):
  1. Base Attack = 30
  2. Elemental: 30 (neutral)
  3. Bonuses (all based on elemental damage of 30):
     - Strength (STR=5): 30 × 0.5 = +15
     - Critical: None
     - Name Match: 30 × 2 = +60 (Prefix 2 match)
  4. Total Attack = 30 + 15 + 60 = 105

  5. Base Armor = 20
  6. Final Damage = MAX(4, 105 - 20) = 85 HP!

  Note: If Prefix 1 matched instead, bonus would be 30 × 8 = +240!
  ```
</div>

### Combat Strategy Tips

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '2rem 0' }}>
  #### Optimization Guidelines

  1. **Prioritize Type Advantages** - +50% damage is a significant boost
  2. **Stack STR for Consistent Damage** - Linear scaling with no cap
  3. **LUCK for Burst Potential** - Critical hits can turn battles
  4. **Match Tier to Level** - Higher tier = more base damage
  5. **Name Matching Endgame** - Massive multipliers at high levels

  #### Common Pitfalls

  * Fighting with type disadvantage (-50% damage reduction)
  * Neglecting STR investment (missing easy damage boost)
  * Using low-tier weapons at high levels
  * Ignoring name match opportunities
</div>

### See Also

* [Battle Guide](/lootsurvivor/guide/battle) - Combat interface and tactics
* [Stats Guide](/lootsurvivor/stats) - Detailed stat explanations
* [Loot System](/lootsurvivor/loot) - Equipment and tier information


import { ContractTable } from "../../components/ContractTable";

## Smart Contracts

Loot Survivor is built on Starknet using the Dojo engine, with all game logic executed fully onchain. The game's smart contracts handle everything from adventurer creation to combat resolution, ensuring transparency and verifiability.

### Death Mountain Contracts

The core game engine powering Loot Survivor.

<ContractTable
  contracts={[
  {
    name: "Game",
    address: "0x6f7c4350d6d5ee926b3ac4fa0c9c351055456e75c92227468d84232fc493a9c",
  },
  {
    name: "Game Token",
    address: "0x5e2dfbdc3c193de629e5beb116083b06bd944c1608c9c793351d5792ba29863",
  },
  {
    name: "Beast",
    address: "0x74abc15c0ddef39bdf1ede2a643c07968d3ed5bacb0123db2d5b7154fbb35c7",
  },
  {
    name: "Adventurer",
    address: "0x3fc7ecd6d577daa1ee855a9fa13a914d01acda06715c9fc74f1ee1a5e346a01",
  },
  {
    name: "Loot",
    address: "0x4c386505ce1cc0be91e7ae8727c9feec66692a92c851b01e7f764ea0143dbe4",
  },
  {
    name: "Objectives",
    address: "0x403224d3586a402bf3d9a7553493ba0d931e306e6aae8472503afdf90083e32",
  },
  {
    name: "Renderer",
    address: "0x6135cd4ee82eb5e7652a636a952c893315914f0655a3cc834ce8b6b1e5ff1cb",
  },
  {
    name: "Settings",
    address: "0x3caf941b916a83550d8f6325802e0cb686c9a0c8b30a23fb9df531ae24d12d0",
  },
]}
/>

### NFT & Token Contracts

<ContractTable
  contracts={[
  {
    name: "Golden Token",
    address: "0x027838dea749f41c6f8a44fcfa791788e6101080c1b3cd646a361f653ad10e2d",
  },
  {
    name: "Beasts",
    address: "0x046da8955829adf2bda310099a0063451923f02e648cf25a1203aac6335cf0e4",
  },
]}
/>

### Governance Contracts

<ContractTable
  contracts={[
  {
    name: "SURVIVOR Token",
    address: "0x042dd777885ad2c116be96d4d634abc90a26a790ffb5871e037dd5ae7d2ec86b",
  },
  {
    name: "Survivor Controller",
    address: "0x041bb7729efa185f2cab327de0a668886302f1d4969e3edf504c4741648f858b",
  },
  {
    name: "Survivor Governor",
    address: "0x050897ea9df71b661b8eac53162be37552e729ee9d33a6f9ae0b61c95a11209e",
  },
]}
/>

### Ecosystem Contracts

<ContractTable
  contracts={[
  {
    name: "Beast Mode",
    address: "0x00a67ef20b61a9846e1c82b411175e6ab167ea9f8632bd6c2091823c3629ec42",
  },
  {
    name: "Dungeon Ticket",
    address: "0x035f581b050a39958b7188ab5c75daaa1f9d3571a0c032203038c898663f31f8",
  },
  {
    name: "Free Games Claims",
    address: "0x07713b8aac77a664792bce1c6cb66649bae64dea85ed5d24bbb0bd3629d66899",
  },
  {
    name: "PG World",
    address: "0x02ef591697f0fd9adc0ba9dbe0ca04dabad80cf95f08ba02e435d9cb6698a28a",
  },
  {
    name: "Token Event Relayer",
    address: "0x2f1c516fa4d2c41f2021edc3b46f33326e73755e55982374381150e6d8d12df",
  },
  {
    name: "Minigame Registry",
    address: "0x06e9c39be20dee2800407fe6cb22214a96a71d339940d6f21fcb354604b6cc7e",
  },
  {
    name: "Denshokan",
    address: "0x036017e69d21d6d8c13e266eabb73ef1f1d02722d86bdcabe5f168f8e549d3cd",
  },
  {
    name: "Budokan",
    address: "0x58f888ba5897efa811eca5e5818540d35b664f4281660cd839cd5a4b0bf4582",
  },
]}
/>

### Development Resources

* [GitHub Repository](https://github.com/Provable-Games/death-mountain) - Source code and documentation
* [Dojo Engine](https://dojoengine.org/) - Framework powering the game
* [Starknet Documentation](https://docs.starknet.io/) - Layer 2 blockchain platform

### Contract Interaction

Players interact with the smart contracts through:

* **Game Interface**: Main game client at lootsurvivor.io
* **Direct Calls**: Advanced users can call contract functions directly
* **Block Explorers**: View transactions and state on Starkscan or Voyager

All game actions are recorded onchain, providing complete transparency and allowing for independent verification of gameplay mechanics.

### Verification Status

Several contracts have been verified on Voyager for enhanced transparency:

* **SURVIVOR Token**: Verified ✓
* **Survivor Controller**: Verified ✓
* **Survivor Governor**: Verified ✓


## Corpse Token ($CORPSE)

<div style={{textAlign: "center", margin: "2rem 0"}}>
  <img src="/docs/corpse-token.png" alt="Corpse Token" style={{maxWidth: "300px", margin: "0 auto"}} />
</div>

### Overview

$CORPSE is an ERC20 token on Starknet earned by extracting value from your fallen adventurers in Loot Survivor: Beast Mode, created alongside [Summit](/summit). When one of your adventurers dies, you can extract $CORPSE tokens proportional to their level. Currently, the only known use case for $CORPSE is increasing beast health in [Summit](/summit/beast-upgrades).

#### At a Glance

* **Standard**: ERC20 on Starknet
* **Supply**: Uncapped — minted continuously as adventurers fall in Loot Survivor: Beast Mode
* **Earning**: 1 $CORPSE per adventurer level (extracted from dead adventurers you own)
* **Current Use**: Increasing beast health in [Summit](/summit/beast-upgrades)
* **Contract Address**: TBA

### How to Earn $CORPSE

$CORPSE tokens are earned exclusively through [Loot Survivor](/lootsurvivor) gameplay:

* Play Loot Survivor: Beast Mode and level up your adventurer
* When your adventurer dies, they become eligible for extraction
* Extract $CORPSE through the Summit interface
* You receive **1 $CORPSE per adventurer level**

**Example:** A dead level 15 adventurer yields **15 $CORPSE**. A dead level 30 adventurer yields **30 $CORPSE**.

The higher you level your adventurers before they fall, the more $CORPSE you can extract. This turns every loss in Loot Survivor into a resource for Summit.

#### Retroactive Claims

Adventurers that died before $CORPSE was introduced are still eligible. If you have dead adventurers from past Loot Survivor games, you can extract $CORPSE from them immediately — meaning you may already be sitting on a stockpile of claimable tokens.

### What $CORPSE Is Used For

$CORPSE is currently used in [Summit](/summit) to permanently increase your beast's health. See the [Beast Upgrades](/summit/beast-upgrades) guide for full details on health enhancement and costs.

### Token Economics

$CORPSE creates a new layer to the Loot Survivor ecosystem — even when your adventurers die, they contribute value:

1. **Play Loot Survivor: Beast Mode** → Adventurer dies → Extract $CORPSE based on level
2. **Spend $CORPSE in Summit** → Increase beast health → Hold the Summit longer
3. **Longer Summit holds** → More $SURVIVOR earned → Greater ecosystem participation

Since $CORPSE has no supply cap, the token continues to be minted as long as adventurers are dying in Loot Survivor. Higher-level adventurers yield proportionally more tokens, rewarding skilled players who push deeper into the game before falling.


## Dungeon Tickets

### Overview

<div
  style={{
  display: "flex",
  alignItems: "center",
  gap: "2rem",
  marginBottom: "2rem",
}}
>
  <div style={{ flex: "1" }}>
    Dungeon tickets are your entry pass to [Beast
    Mode](/lootsurvivor/game-modes) in Loot Survivor. Each ticket grants access
    to the Dungeon where you can collect unique [Beast
    NFTs](/lootsurvivor/beasts) and earn [SURVIVOR tokens](/lootsurvivor/token)
    through gameplay.
  </div>

  <img src="/docs/lootsurvivor/dungeon_ticket.png" alt="Dungeon Ticket" style={{ width: "200px", flexShrink: 0 }} />
</div>

### Dynamic Pricing System

Loot Survivor uses an innovative dynamic pricing model for dungeon tickets:

* **Continuous Emission**: Tickets are continuously emitted over time
* **Real-Time Adjustment**: Price adjusts based on demand - can move up or down
* **Transparent Pricing**: Live price is always visible before purchase
* **Market-Driven**: Price discovery happens naturally through supply and demand

#### Issuance Schedule

The ticket issuance system is designed for long-term sustainability:

* **Total Supply**: 100 million games over 132 years
* **Base Rate**: \~2,000 games issued per day
* **Duration**: Maximum issuance period of 132 years
* **Distribution**: Equal rate emission ensures predictable supply

#### Adaptive Issuance Mechanism

The protocol includes an automatic adjustment mechanism to maintain market balance:

* **Price Monitoring**: Contract continuously monitors ticket prices
* **Trigger Threshold**: If price falls below $1 for 3 consecutive days
* **Automatic Response**: Issuance rate halves to reduce supply pressure
* **Market Protection**: Helps maintain sustainable pricing over the long term

This adaptive system ensures that ticket supply responds to market conditions, protecting both players and the ecosystem from extreme price volatility while maintaining accessibility.

#### Governance Control

All key parameters of the dungeon ticket system are fully configurable by [SURVIVOR token](/lootsurvivor/token) holders through on-chain governance:

* **Issuance Parameters**: Emission rate, halving triggers, and total supply
* **Payment Tokens**: Which tokens are accepted for ticket purchases
* **Price Thresholds**: Adjustment triggers and response mechanisms
* **Distribution Ratios**: Revenue split between treasury and veLORDS

This decentralized control ensures the community can adapt the system to changing market conditions and player needs over time.

### What You Get

Each dungeon ticket provides:

#### 🐉 Beast Collection

* Access to collect unique [Beast NFTs](/lootsurvivor/beasts/collectibles)
* 85% of the total Beast supply still available in the Dungeon
* Each Beast is a unique, tradeable NFT

#### 💰 SURVIVOR Tokens

* Earn [SURVIVOR tokens](/lootsurvivor/token/tokenomics) based on your performance
* Tokens = level reached (starting at level 3)
* **Limited Time Boost**: 4x SURVIVOR rewards during weeks 2-4

#### 🎯 Wanted Beast Bounties

* Hunt [special Beasts](/lootsurvivor/beasts/wanted-beasts) with 100,000 STRK bounty (\~$15,000)
* Split equally between three legendary Beasts
* First adventurer to defeat each Beast claims their bounty

### How to Purchase

Dungeon tickets can be purchased with **any token** on Starknet - ETH, USDC, STRK, LORDS, and more. The system automatically handles the conversion, making it convenient regardless of what tokens you hold.

<div style={{ textAlign: "center", margin: "2rem 0" }}>
  <img
    src="/docs/lootsurvivor/ticket-purchase.png"
    alt="Ticket Purchase Interface"
    style={{
    maxWidth: "600px",
    width: "100%",
    margin: "0 auto",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  />

  <p style={{ marginTop: "0.5rem", fontSize: "0.9em", fontStyle: "italic" }}>
    Purchase tickets with any token - the interface shows live pricing
  </p>
</div>

#### Option 1: Direct Purchase

Purchase through the [Ekubo Protocol](https://app.ekubo.org) AMM at the live market price. This is the most direct method for experienced DeFi users. Select your preferred token and the system handles the swap automatically.

#### Option 2: Simple Checkout

Use [Cartridge](https://cartridge.gg) for easy entry with card/fiat payment. Perfect for newcomers to Web3 gaming. Credit card payments are converted seamlessly.

#### Pro Strategy: Dollar-Cost Averaging

The most efficient purchasing method is placing a DCA (Dollar-Cost Averaging) order through Ekubo:

* **Spread purchases over time** to smooth out price fluctuations
* **Often achieves better average price** than buying all at once
* **Automated execution** reduces manual effort
* Learn more: [Ekubo DCA Guide](https://docs.ekubo.org/user-guides/dollar-cost-average-orders)

<div
  style={{
  background: "#1a1a1a",
  padding: "1rem",
  borderRadius: "8px",
  margin: "1.5rem 0",
  fontSize: "0.9em",
  color: "#999",
}}
>
  <strong style={{ color: "#bbb" }}>Note on Token Flow:</strong> When you
  purchase a ticket with any token, the protocol automatically converts it to
  LORDS tokens. These LORDS are then distributed: 20% to veLORDS holders and 80%
  used for SURVIVOR token buybacks, supporting both the Bibliotheca ecosystem
  and the Survivor treasury.
</div>

### Revenue Distribution

All ticket proceeds are distributed transparently on-chain:

#### 80% → Survivor Treasury

* Automated [SURVIVOR token](/lootsurvivor/token) buybacks via TWAMM
* DAO-controlled treasury for ecosystem growth
* Governed by SURVIVOR token holders
* Pre-seeded at genesis for sustainability

#### 20% → veLORDS Holders

* Distributed to [veLORDS](https://realms.world) stakers
* Rewards the [Bibliotheca DAO](https://bibliothecadao.xyz) ecosystem
* Recognizes Bibliotheca as the original incubator

### Key Benefits

<div
  style={{
  display: "grid",
  gridTemplateColumns: "repeat(auto-fit, minmax(250px, 1fr))",
  gap: "1rem",
  margin: "2rem 0",
}}
>
  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>🎮 Beast Collection</h4>
    <p>Enter the dungeon and battle to collect unique Beast NFTs</p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>💎 NFT Collection</h4>

    <p>
      Every [Beast](/lootsurvivor/beasts) is a unique, tradeable NFT with
      varying rarity
    </p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>📈 Token Rewards</h4>

    <p>
      Earn [SURVIVOR governance tokens](/lootsurvivor/token) based on your skill
    </p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>🏆 Bounty Hunting</h4>

    <p>
      Chase [special Beasts](/lootsurvivor/beasts/wanted-beasts) for substantial
      STRK rewards
    </p>
  </div>
</div>

### Frequently Asked Questions

#### When should I buy tickets?

With dynamic pricing, tickets can be cheaper during low-demand periods. Consider using DCA orders to spread your purchases over time.

#### How many games can I play with one ticket?

One ticket grants you one entry into the dungeon for a Beast collection attempt. Each dungeon run requires a new ticket.

#### Can ticket prices go down?

Yes! Unlike fixed-price models, our dynamic system allows prices to decrease when demand is low, creating opportunities for strategic buyers.

#### What happens to my ticket after use?

Each ticket is consumed when you enter the dungeon, regardless of the outcome. You'll need a new ticket for each dungeon run.

### Get Started

Ready to enter the Dungeon? Purchase your ticket at [lootsurvivor.io](https://lootsurvivor.io) and start your Beast hunting adventure today!


## Frequently Asked Questions

### General

**What is Loot Survivor?**

Loot Survivor is a fully onchain dungeon crawler RPG built on Starknet. Every action, from combat to loot generation, happens directly on the blockchain, making the game transparent, verifiable, and permanent.

**Is Loot Survivor free to play?**

Yes, Loot Survivor has a completely free game mode for players to practice their skills. For the full dungeon experience, a ticket is required which can be purchased directly through the game. No gas required.

**What do I need to play?**

* **Free Version:** No wallet, gas, or ticket required — just a modern browser (Chrome, Firefox, Safari, Edge).
* **Full Version:** A Cartridge Controller wallet (for VRF support) and a dungeon ticket purchased through the game. No gas fees.

**Is the game mobile-friendly?**

Yes. Loot Survivor has a fully responsive design with a dedicated mobile interface optimized for touch controls.

### Gameplay

**How do I start playing?**

Choose your game mode and click "New Game" to start exploring. See the [Getting Started Guide](/lootsurvivor/guide/getting-started) for detailed instructions.

**What happens when my adventurer dies?**

Death is permanent — your adventurer's journey ends but earned assets remain onchain forever. Start a new adventure anytime.

**Can I have multiple adventurers?**

Yes. Each adventurer is a separate onchain token with unique progression.

**How does combat work?**

Turn-based combat with rock-paper-scissors type advantages (plus or minus 50% damage). Each weapon/armor type beats one and loses to another. See: [Battle Guide](/lootsurvivor/guide/battle) and [Combat Mechanics](/lootsurvivor/combat).

**What are the different stats?**

Seven core stats: STR (damage), DEX (flee), VIT (HP), INT (obstacles), WIS (ambush), CHA (prices), LUCK (crits). Each affects combat and exploration differently. Full details: [Stats Guide](/lootsurvivor/stats).

**How do items work?**

5 tiers (T5 common to T1 legendary). Items level up and unlock suffixes (Lv15) and prefixes (Lv19+) for bonuses. See: [Loot Guide](/lootsurvivor/loot).

**What's the best strategy?**

No single best strategy. Focus on type advantages, stat balance, tactical decisions, and resource management. See: [Battle Guide](/lootsurvivor/guide/battle).

### Technical

**What blockchain is Loot Survivor on?**

Loot Survivor runs on Starknet, a Layer 2 scaling solution for Ethereum. Benefits include low fees (under $0.01 per transaction), fast confirmations (1-3 seconds), and Ethereum-level security.

**Are the game outcomes truly random?**

Uses VRF (Verifiable Random Function) seeds by default for true randomness. Can be configured to use deterministic seeds in settings.

**Can I verify the game logic?**

Yes. All contracts are open source and verified on Starknet. You can inspect the code on [GitHub](https://github.com/Provable-Games/death-mountain) and verify any game action onchain.

**How are gas fees kept low?**

Optimizations include packed storage, batch operations, and efficient algorithms, plus Starknet's L2 scaling benefits.

### Economic

**How does the market work?**

The in-game market refreshes when you level up, uses VRF seeds for item generation, and prices decrease with Charisma. No real money transactions between players.

**Can I trade items with other players?**

Currently, direct player-to-player trading is not implemented. All trading happens through the in-game market system.

**Are there rewards for playing?**

Yes. When you kill beasts during gameplay, you collect them and earn $SURVIVOR tokens on collection. [Budokan](/budokan) tournaments with prize pools are another way to earn rewards. Check [Discord](https://discord.gg/Q36rUxS66c) for current tournament info and schedules.

### Wallet & Account

**Which wallets are supported?**

For VRF ([Budokan](/budokan) tournament) mode, Cartridge Controller is required. For standard mode, any Starknet-compatible wallet works (Argent X, Braavos, etc.).

**I lost access to my wallet. Can I recover my adventurer?**

If you lose wallet access, you lose access to your adventurers. Always keep your recovery phrase secure and backed up.

**Can I play on multiple devices?**

Yes. Your adventurers are tied to your wallet address, not your device. Play from any device where you can access your wallet.

**Why do transactions sometimes fail?**

Common reasons include network congestion and wallet not being properly connected.

### Advanced

**Can I build on top of Loot Survivor?**

Yes. Loot Survivor is open source and designed to be composable. You can build custom frontends, create analytical tools, extend game mechanics, and integrate with other protocols.

**How do I integrate Loot Survivor into my app?**

See our [Integration Guide](/lootsurvivor/technical/integration) for detailed instructions on building with Loot Survivor's contracts.

**What's the maximum level?**

There is no hard level cap. The theoretical maximum depends on your ability to survive increasingly difficult challenges.

**How are beasts generated?**

Beasts are generated from VRF seeds based on your adventurer's level, a random seed value, and tier distribution tables. See: [Combat Mechanics](/lootsurvivor/combat).

**Can I predict market items?**

No. Market items use VRF seeds for true randomness (unless configured otherwise in settings).

### Troubleshooting

**The game won't load**

Try these steps: clear browser cache (Ctrl+Shift+Del), disable ad blockers (most common cause of wallet connection issues), try Chrome or Firefox, check [status.starknet.io](https://status.starknet.io), and ensure JavaScript is enabled.

**Transactions are stuck**

Wait for network congestion to clear, check block explorer, refresh page, or reconnect wallet. More help: [Getting Started Guide](/lootsurvivor/guide/getting-started).

**I can't connect my wallet**

Ensure correct controller login details, check network, refresh page, or try a different browser. Setup help: [Getting Started Guide](/lootsurvivor/guide/getting-started).

**The game shows incorrect data**

This is a sync issue. Refresh the page, clear cache, reconnect wallet, or wait for the indexer.

### Community

**How can I contribute?**

Report bugs on [GitHub](https://github.com/Provable-Games/death-mountain/issues), suggest features in Discord, build tools and integrations, or create content and guides.

**Where can I get help?**

* [Discord Community](https://discord.gg/Q36rUxS66c)
* [Twitter](https://twitter.com/lootsurvivor)
* [GitHub Discussions](https://github.com/Provable-Games/death-mountain/discussions)

**Are there tournaments?**

Yes. Regular tournaments with prize pools are held on [Budokan](/budokan), the permissionless tournament platform. Check Discord for announcements and schedules.

### Legal & Safety

**Is Loot Survivor audited?**

The smart contracts have not undergone an official audit yet. As with all blockchain applications, use at your own risk.

**Is this gambling?**

Loot Survivor is a skill-based game with random elements. The outcome depends on player decisions and strategy, not purely chance.

**What data is collected?**

Only onchain data (transactions, game actions) is recorded. No personal information is collected or stored off-chain.

**Can I lose money playing?**

You pay entry fees for certain game modes. Entry fees can be paid in any supported token. Never spend more than you can afford to lose.

### Getting More Help

If your question isn't answered here:

1. Check the [comprehensive guides](/lootsurvivor/guide)
2. Read the [technical documentation](/lootsurvivor/technical/architecture)
3. Ask in [Discord](https://discord.gg/Q36rUxS66c)
4. Open a [GitHub issue](https://github.com/Provable-Games/death-mountain/issues)




## Golden Token V2

<div style={{textAlign: "center", margin: "2rem 0"}}>
  <img src="/docs/lootsurvivor/golden-token.gif" alt="Golden Token V2" style={{maxWidth: "300px", margin: "0 auto"}} />
</div>

### Overview

Golden Token V2 is the successor to the original Golden Token NFT collection on Starknet, modernized for full ecosystem compatibility and built entirely on-chain. V2 preserves the provenance of the original via a fully onchain airdrop while upgrading to modern standards and tooling.

V2 expands the collection by airdropping seven new ERC721 tokens to each of the 160 V1 holders, resulting in a total supply of 1,120. Each V2 token grants its holder one free Loot Survivor game per week, forever.

#### At a Glance

* **Supply**: 1,120 tokens (160 holders × 7 each)
* **Distribution**: Airdropped in seven rounds to current V1 holders at execution time
* **Compatibility**: OpenZeppelin ERC721 + ERC2981 on Cairo 2.11.4
* **Governance**: ERC721Votes for onchain voting and delegation
* **Metadata**: Fully on-chain JSON + SVG (no base URI, data URI returned)
* **Art**: Animated SVG instead of static PNG

V2 addresses early V1 limitations (pre-standard ERC721) by adopting modern standards and audited components, ensuring wallet/marketplace support, enforceable royalties, and native governance—while keeping the experience faithful to the original Golden Token vision.

### The Origin Story

The original Golden Tokens were launched on October 31st, 2023, alongside the inaugural release of Loot Survivor. In a true fair-launch fashion, Golden Tokens were made available through a three-week open edition mint with:

* ✅ No allowlist
* ✅ No mint limits
* ✅ No team allocation
* 💰 Cost: 75 games' worth of Loot Survivor

V1 Golden Tokens provided a simple utility: one free game of Loot Survivor per day. V2 Golden Tokens now provide one free game of Loot Survivor per week.

### V2: Technical Evolution & Enhanced Ecosystem

The original Golden Tokens were pioneering NFTs on Starknet, created before formal ERC721 specifications were available. This early adoption meant inconsistent compatibility - not all wallets, block explorers, and marketplaces properly support V1 tokens.

Golden Token V2 addresses these limitations while expanding the ecosystem:

#### Technical Improvements

* **Full ERC721 Compliance**: Built with OpenZeppelin 2.0.0 specifications for universal compatibility
* **Modern Cairo**: Upgraded to Cairo 2.11.4 from 2.1.0 Cairo contracts
* **Ecosystem Compatibility**: Full support across all Starknet wallets, explorers, and marketplaces
* **Onchain Governance**: Integrated ERC721Votes enables holders to formally express views through onchain voting
* **Enhanced Security**: Latest audited OpenZeppelin components with comprehensive security patterns

#### Ecosystem Enhancements

* **Increase Optionality**: Weekly games instead of daily, giving holders more flexibility
* **Expand Liquidity**: 7x supply increase (160 → 1,120 tokens) enables more trading and market activity
* **Preserve Legacy**: Original holders receive the entire V2 supply via airdrop
* **Maintain Exclusivity**: No public mint - only original holders can receive V2 tokens

### Key Differences from V1

| Feature        | V1                    | V2                     |
| -------------- | --------------------- | ---------------------- |
| Cairo Version  | Cairo 2.1.0           | Cairo 2.11.4           |
| ERC721 Spec    | OpenZeppelin 0.7.0    | OpenZeppelin 2.0.0     |
| Wallet Support | Limited compatibility | Universal support      |
| Voting         | N/A                   | ERC721Votes integrated |
| Total Supply   | 160 tokens            | 1,120 tokens           |
| Distribution   | Open edition mint     | Airdrop to V1 holders  |
| Game Frequency | 1 free game/day       | 1 free game/week       |
| Launch Date    | October 31, 2023      | September 5th, 2025    |

### Features

* 🎮 **Weekly Gaming Rights**: Each token grants one free Loot Survivor game per week in perpetuity
* 🪂 **Fair Airdrop System**: 7 rounds of airdrops, each distributing 160 tokens to original holders
* 🏛️ **Legacy Preservation**: Rewards early supporters with expanded holdings
* 🗳️ **Onchain Governance**: ERC721Votes enables formal onchain voting for ecosystem decisions
* 🔧 **Full Compatibility**: Works seamlessly with all Starknet wallets, explorers, and marketplaces
* 💰 **Creator Royalties**: 5% royalty on secondary sales via ERC2981 standard
* 🎨 **Fully Onchain**: All metadata and SVG artwork stored and generated onchain
* ⛓️ **Modern Standards**: Built with latest Cairo 2.11.4 and OpenZeppelin 2.0.0

### Technical Architecture

#### Smart Contract Components

The contract leverages battle-tested OpenZeppelin Cairo components:

* **ERC721Component**: Core NFT functionality with metadata extension
* **OwnableComponent**: Administrative access control
* **ERC2981Component**: NFT royalty standard implementation (5% on secondary sales)
* **VotesComponent**: Democratic governance through NFT-based voting
* **SRC5Component**: Interface detection for contract introspection
* **NoncesComponent**: Signature replay protection

#### Airdrop Mechanism

The V2 distribution occurs through a systematic airdrop process:

* **7 Rounds Total**: Each round airdrops 160 new tokens to match the original collection size
* **1:7 Ratio**: Each original Golden Token holder receives 7 V2 Golden Tokens
* **Owner Verification**: Tokens are airdropped to current holders at the time of execution. No snapshots, no merkle trees, no manual claims required


import { ContractTable } from "../../components/ContractTable";
import { Button } from "vocs/components";

![Overview](docs/ls-banner-docs.png)

## Loot Survivor

Loot Survivor is a fully onchain dungeon crawler RPG built on Starknet using the Dojo engine. Navigate through procedurally generated dungeons, battle fierce beasts, overcome deadly obstacles, and collect legendary loot in your quest for survival and glory. The items in the game are dervied from the <a href="https://docs.loot.foundation/" style={{ color: "#3b82f6" }}>Loot</a> project.

<Button href="https://lootsurvivor.io" target="_blank" className="bg-white text-black" size="lg">
  Play Now
</Button>

### Overview

Death Mountain powers Loot Survivor - a token-agnostic, no-code onchain dungeon creator that provides a complete RPG experience. Every action, from combat to loot generation, is verifiable and deterministic on the blockchain.

#### Key Features

<div
  style={{
  display: "grid",
  gridTemplateColumns: "repeat(auto-fit, minmax(250px, 1fr))",
  gap: "1rem",
  margin: "2rem 0",
}}
>
  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>🗡️ Deep RPG Mechanics</h4>
    <p>7 core stats, 8 equipment slots, and level-based progression</p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>👾 75 Unique Beasts</h4>
    <p>From lowly gnomes to mighty dragons, each with distinct behaviors</p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>⚡ 75 Deadly Obstacles</h4>
    <p>Magical, sharp, and crushing hazards to overcome</p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>💎 101 Unique Items</h4>
    <p>Tier-based loot system with evolving item powers</p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>🏪 Dynamic Market</h4>
    <p>Charisma-based pricing and level rotating shop items</p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>🎲 Verifiable Randomness</h4>
    <p>VRF integration for true randomness</p>
  </div>

  <div
    style={{
    background: "#1a1a1a",
    padding: "1rem",
    borderRadius: "8px",
    border: "1px solid #333",
  }}
  >
    <h4>⛓️ Fully Onchain</h4>
    <p>All game logic executed on Starknet</p>
  </div>
</div>

### Game Systems

#### Adventurer System

Create and develop your character with comprehensive RPG mechanics:

* **Stats**: Strength, Dexterity, Vitality, Intelligence, Wisdom, Charisma, Luck
* **Equipment**: Weapon, Chest, Head, Waist, Foot, Hand, Neck, Ring slots
* **Progression**: XP-based leveling with stat point allocation
* **Health**: Starting HP of 100, scalable with Vitality and replenished with potions.

#### Combat System

Engage in strategic turn-based combat against beasts:

* **Combat Types**: Weapon triangle system (Magical > Brute > Hunter > Magical)
* **Critical Hits**: Luck based strikes, grows with better Jewelry
* **Flee Mechanics**: Dexterity-based escape chances

#### Exploration

Navigate through dangerous dungeons:

* **Beasts**: Fight 75 different beast types with scaling difficulty
* **Obstacles**: 75 unique environmental hazards
* **Loot**: Find items, gold, and XP through exploration
* **Strategic Choices**: Decide when to fight, flee, or explore

#### Item System

Collect and upgrade powerful equipment:

* **Tier System**: T1 (Legendary) - T5 (Common) items with inverse pricing
* **Item Evolution**: Items gain "greatness" unlocking suffixes and prefixes
* **Special Powers**: 16 unique suffixes providing stat bonuses
* **Type Advantages**: Strategic equipment choices based on enemy types

### Documentation

#### 🎮 Getting Started

* [Game Modes](/lootsurvivor/game-modes) - Free vs. Full game modes
* [Getting Started Guide](/lootsurvivor/guide/getting-started) - Your first adventure
* [Dungeon Tickets](/lootsurvivor/dungeon-tickets) - Dynamic pricing and Beast Mode access
* [Golden Token](/lootsurvivor/golden-token) - Premium NFT collection for unlimited weekly gameplay
* [Settings](/lootsurvivor/settings) - Game configuration and VRF options
* [FAQ](/lootsurvivor/faq) - Frequently asked questions

#### ⚔️ Game Mechanics

* [Stats System](/lootsurvivor/stats) - Character attributes and progression
* [Combat Mechanics](/lootsurvivor/combat) - Damage calculations and formulas
* [Battle Guide](/lootsurvivor/guide/battle) - Combat tactics and interface
* [Exploration](/lootsurvivor/guide/explore) - Discovery and obstacles
* [Character Upgrade](/lootsurvivor/guide/upgrade) - Leveling and stat allocation

#### 🎒 Items & Creatures

* [Loot System](/lootsurvivor/loot) - Equipment, tiers, and bonuses
  * [Jewelry](/lootsurvivor/loot/jewelry) - Rings, amulets, and accessories
  * [Suffix Boosts](/lootsurvivor/loot/suffix-boost) - Item enhancement system
  * [Prefixes](/lootsurvivor/loot/prefixes) - Complete prefix and suffix reference
* [Beasts](/lootsurvivor/beasts) - Combat types, tiers, and strategies
  * [Beast Collectibles](/lootsurvivor/beasts/collectibles) - Achievement system
  * [Wanted Beasts](/lootsurvivor/beasts/wanted-beasts) - Special bounties with STRK rewards

### Technical Resources

#### 🔧 Development & Contracts

* [Smart Contracts](/lootsurvivor/contracts) - Contract addresses and technical details
* [GitHub Repository](https://github.com/Provable-Games/death-mountain) - Source code and development
* [Dojo Engine](https://dojoengine.org/) - Framework powering the game

#### 🌐 Community

* [Discord Community](https://discord.gg/Q36rUxS66c) - Join the community
* [Twitter](https://twitter.com/lootsurvivor) - Latest updates and news


## Market System

The market is your lifeline in Loot Survivor, offering equipment upgrades and life-saving potions. Understanding pricing mechanics and market generation helps you make strategic purchasing decisions that can mean the difference between victory and defeat.

> **🛍️ Market Philosophy:** Every gold piece spent should advance your survival strategy!

### Market Overview

<div
  style={{
backgroundColor: "rgba(251, 191, 36, 0.1)",
border: "2px solid #fbbf24",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#fbbf24" }}>🏪 Market Mechanics</h3>

  <ul style={{ marginBottom: 0 }}>
    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Duration:</strong> Same market persists for your entire level
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Refresh:</strong> New randomly generated market on next level up
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Purchases:</strong> Buy as many items as you can afford
    </li>

    <li>
      <strong>Inventory:</strong> Limited to 15 bag slots + 8 equipped items
    </li>
  </ul>
</div>

***

## Item Pricing

### Base Pricing System

<div
  style={{
backgroundColor: "rgba(59, 130, 246, 0.1)",
border: "2px solid #3b82f6",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#3b82f6" }}>💰 Equipment Pricing Formula</h3>

  <div style={{ marginBottom: "1rem" }}>
    <strong>Base Price = Item Tier × 4</strong>
  </div>

  <table style={{ width: "100%", marginBottom: "1rem" }}>
    <thead>
      <tr>
        <th>Tier</th>
        <th>Base Price</th>
        <th>With 10 CHA</th>
        <th>With 20 CHA</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>T5 (Common)</td>
        <td>20 gold</td>
        <td>10 gold</td>
        <td>1 gold (min)</td>
      </tr>

      <tr>
        <td>T4</td>
        <td>16 gold</td>
        <td>6 gold</td>
        <td>1 gold (min)</td>
      </tr>

      <tr>
        <td>T3</td>
        <td>12 gold</td>
        <td>2 gold</td>
        <td>1 gold (min)</td>
      </tr>

      <tr>
        <td>T2</td>
        <td>8 gold</td>
        <td>1 gold (min)</td>
        <td>1 gold (min)</td>
      </tr>

      <tr>
        <td>T1 (Legendary)</td>
        <td>4 gold</td>
        <td>1 gold (min)</td>
        <td>1 gold (min)</td>
      </tr>
    </tbody>
  </table>

  <div style={{ marginBottom: "1rem" }}>
    <strong>Charisma Discount:</strong> -1 gold per CHA point (minimum 1 gold)
  </div>

  <div
    style={{ 
  backgroundColor: "rgba(251, 191, 36, 0.2)", 
  padding: "1rem", 
  borderRadius: "6px",
  border: "1px solid #fbbf24"
}}
  >
    <strong>💡 Important:</strong> All purchased items start at Greatness 1. A T1 item may initially be weaker than your leveled T5 equipment - you need to gain experience and level the item to unlock its full potential!
  </div>
</div>

***

## Potion System

### Health Potions

<div
  style={{
backgroundColor: "rgba(34, 197, 94, 0.1)",
border: "2px solid #22c55e",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#22c55e" }}>🧪 Potion Mechanics</h3>

  <div style={{ marginBottom: "1rem" }}>
    <strong>Health Restored:</strong> +10 HP per potion
  </div>

  <div style={{ marginBottom: "1rem" }}>
    <strong>Purchase Limit:</strong> Unlimited (buy as many as you can afford)
  </div>

  <div style={{ marginBottom: "1rem" }}>
    <strong>Price Formula:</strong>

    <div style={{ fontFamily: "monospace", marginLeft: "1rem", marginTop: "0.5rem" }}>
      Base Price = 1 gold × Adventurer Level<br />
      CHA Discount = 2 gold per CHA point<br />
      Final Price = Base - Discount (minimum 1 gold)
    </div>
  </div>
</div>

#### Potion Pricing Table

| Level | Base Price | 1 CHA | 5 CHA | 10 CHA | 15 CHA |
| ----- | ---------- | ----- | ----- | ------ | ------ |
| 1     | 1g         | 1g    | 1g    | 1g     | 1g     |
| 5     | 5g         | 3g    | 1g    | 1g     | 1g     |
| 10    | 10g        | 8g    | 1g    | 1g     | 1g     |
| 20    | 20g        | 18g   | 10g   | 1g     | 1g     |
| 50    | 50g        | 48g   | 40g   | 30g    | 20g    |

> **💡 Strategy:** High CHA makes potions extremely cheap, allowing bulk healing purchases!

***

## Market Generation

<div
  style={{
backgroundColor: "rgba(147, 51, 234, 0.1)",
border: "2px solid #9333ea",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#9333ea" }}>🎲 How Markets Generate</h3>

  <p style={{ marginBottom: "1rem" }}>
    Each level generates a unique market through RNG:
  </p>

  <ol style={{ marginBottom: 0 }}>
    <li style={{ marginBottom: "0.75rem" }}>
      Game rolls for <strong>25 random items</strong>
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      Duplicate items are <strong>removed</strong> (only one instance appears)
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      Market size varies from <strong>1-25 items</strong>
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      Small markets = many duplicate rolls occurred
    </li>

    <li>
      Market remains <strong>constant until next level</strong>
    </li>
  </ol>
</div>

#### Market Size Probabilities

* **20-25 items:** Common (most markets)
* **15-19 items:** Occasional
* **10-14 items:** Uncommon
* **5-9 items:** Rare
* **1-4 items:** Very rare (extreme bad luck)

***

## Market Tips & Tricks

<div
  style={{
backgroundColor: "rgba(26, 26, 26, 0.8)",
border: "2px solid #666",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem" }}>🎯 Pro Market Strategies</h3>

  <ul style={{ marginBottom: 0 }}>
    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Check Everything:</strong> Scroll through entire market - gems might be at the bottom
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Type Coverage:</strong> Prioritize items that give you type advantages
    </li>

    <li>
      <strong>Empty Slots:</strong> Any armor is better than no armor
    </li>
  </ul>
</div>

### Common Mistakes to Avoid

* **Overspending Early:** Don't buy everything just because you can
* **Ignoring CHA:** Even 3 CHA dramatically reduces T5 prices
* **Potion Neglect:** Always keep HP topped up between fights

***

## Summary

The market system rewards strategic planning and smart stat allocation. High Charisma turns the market into your personal armory, while understanding pricing helps you maximize every gold piece. Remember: the best deal is the item that keeps you alive!

**Key Market Principles:**

* Markets refresh on level up only
* CHA dramatically reduces all prices
* Potions scale with level but CHA discount is powerful
* Small markets mean bad RNG - work with what you get
* Every purchase should advance your survival strategy


## Platform Comparison

Loot Survivor delivers a consistent, high-quality gaming experience across all platforms. Whether you're at your desk or on the move, enjoy the same depth of gameplay with interfaces optimized for each device type.

### Desktop vs Mobile Experience

<div
  style={{
backgroundColor: "rgba(59, 130, 246, 0.1)",
border: "2px solid #3b82f6",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#3b82f6" }}>🎮 Same Core Experience</h3>

  <p style={{ marginBottom: "1rem", lineHeight: "1.6" }}>
    Both platforms offer identical gameplay mechanics, features, and progression systems. The differences lie in how the interface is presented and optimized for each device type.
  </p>

  <ul style={{ marginBottom: 0, paddingLeft: "1.5rem" }}>
    <li style={{ marginBottom: "0.5rem" }}>✅ Same game mechanics and rules</li>
    <li style={{ marginBottom: "0.5rem" }}>✅ Identical stats, combat, and progression</li>
    <li style={{ marginBottom: "0.5rem" }}>✅ Full market and inventory systems</li>
    <li style={{ marginBottom: "0.5rem" }}>✅ Complete blockchain integration</li>
    <li>✅ Cross-platform wallet compatibility</li>
  </ul>
</div>

***

### Desktop Interface

<div style={{ maxWidth: "1000px", margin: "2rem auto" }}>
  <video
    src="/docs/lootsurvivor/desktop.mp4"
    autoPlay
    loop
    muted
    style={{
    width: "100%",
    display: "block",
    margin: "0 auto",
    borderRadius: "8px",
    border: "2px solid #333",
  }}
  />

  <em style={{ display: "block", textAlign: "center", marginTop: "0.5rem" }}>
    Desktop interface showing AI-powered visuals and interactive gameplay
  </em>
</div>

#### Desktop Advantages

<div
  style={{
backgroundColor: "rgba(26, 26, 26, 0.8)",
border: "1px solid #4ade80",
borderRadius: "8px",
padding: "1.5rem",
marginTop: "2rem",
marginBottom: "2rem"
}}
>
  <h4 style={{ marginTop: 0, marginBottom: "1rem", color: "#4ade80" }}>🖥️ Full High-Resolution AI Visuals & Animations</h4>

  <p style={{ marginBottom: 0, lineHeight: "1.6" }}>
    Experience cutting-edge AI-powered graphics with detailed animations, rich visual effects, and immersive high-resolution artwork. Perfect for deep exploration sessions where visual fidelity enhances the adventure.
  </p>
</div>

***

### Mobile Interface

<div style={{ maxWidth: "400px", margin: "2rem auto" }}>
  <video
    src="/docs/lootsurvivor/mobile.mp4"
    autoPlay
    loop
    muted
    style={{
    width: "100%",
    display: "block",
    margin: "0 auto",
    borderRadius: "8px",
    border: "2px solid #333",
  }}
  />

  <em style={{ display: "block", textAlign: "center", marginTop: "0.5rem" }}>
    Mobile pixel-art interface with fast-paced touch gameplay
  </em>
</div>

#### Mobile Advantages

<div
  style={{
backgroundColor: "rgba(26, 26, 26, 0.8)",
border: "1px solid #f59e0b",
borderRadius: "8px",
padding: "1.5rem",
marginTop: "2rem",
marginBottom: "2rem"
}}
>
  <h4 style={{ marginTop: 0, marginBottom: "1rem", color: "#f59e0b" }}>📱 Mobile-Friendly UI Where Speed is Priority</h4>

  <p style={{ marginBottom: 0, lineHeight: "1.6" }}>
    Streamlined pixel-art interface optimized for lightning-fast gameplay. Touch controls, instant responses, and efficient layouts ensure quick decision-making perfect for on-the-go adventures and rapid combat encounters.
  </p>
</div>

***

### Choose Your Adventure

Both platforms offer the complete Loot Survivor experience with their own unique advantages. Whether you prefer the immersive desktop experience or the convenience of mobile gaming, your adventure awaits!

<div
  style={{
textAlign: "center",
backgroundColor: "rgba(34, 197, 94, 0.1)",
border: "2px solid #22c55e",
borderRadius: "8px",
padding: "2rem",
marginTop: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#22c55e" }}>Ready to Start Playing?</h3>

  <p style={{ marginBottom: "1.5rem", fontSize: "1.1rem" }}>
    Visit <strong>lootsurvivor.io</strong> on any device and begin your adventure into Death Mountain!
  </p>

  <a
    href="/lootsurvivor/guide/getting-started"
    style={{ 
    color: "#22c55e", 
    textDecoration: "none",
    fontWeight: "600",
    fontSize: "1.1rem"
  }}
  >
    📖 Back to Getting Started Guide →
  </a>
</div>




## Skull Token ($SKULL)

<div style={{textAlign: "center", margin: "2rem 0"}}>
  <img src="/docs/skull-token.png" alt="Skull Token" style={{maxWidth: "300px", margin: "0 auto"}} />
</div>

### Overview

$SKULL is an ERC20 token on Starknet that represents beast kills in Loot Survivor, created alongside [Summit](/summit). Every time one of your beasts kills an adventurer, you can claim 1 $SKULL. Currently, the only known use case for $SKULL is upgrading beasts in [Summit](/summit/beast-upgrades).

#### At a Glance

* **Standard**: ERC20 on Starknet
* **Supply**: Uncapped — minted continuously as adventurers are killed in Loot Survivor
* **Earning**: 1 $SKULL per adventurer killed by your beast
* **Current Use**: Beast upgrades in [Summit](/summit/beast-upgrades)
* **Contract Address**: TBA

### How to Earn $SKULL

$SKULL tokens are earned exclusively through [Loot Survivor](/lootsurvivor) gameplay:

* Own a beast NFT
* When an adventurer encounters your beast and is killed, you can claim **1 $SKULL**
* Tokens accumulate across all your beasts — every kill counts

The more beasts you own and the stronger they are (tier 1 beasts kill most adventurers), the more adventurers they'll defeat and the more $SKULL you'll accumulate.

#### Retroactive Claims

Beasts that haven't been minted yet may have already slain adventurers in Loot Survivor. Once you mint a beast, you can claim $SKULL for all of its past kills — meaning a newly minted beast could come with multiple $SKULL ready to claim.

### What $SKULL Is Used For

$SKULL is currently used in [Summit](/summit) to upgrade your beasts with attributes and abilities. See the [Beast Upgrades](/summit/beast-upgrades) guide for full details on available upgrades and costs.

### Token Economics

$SKULL creates a natural connection between Loot Survivor and Summit:

1. **Collect beasts** → Own beast NFTs through Loot Survivor gameplay or the [marketplace](https://beast-dex.vercel.app/marketplace)
2. **Beasts kill adventurers** → Earn $SKULL from kills in Loot Survivor
3. **Spend $SKULL in Summit** → Upgrade beasts → Compete for $SURVIVOR rewards
4. **Stronger beasts in Summit** → More $SURVIVOR earned → Greater ecosystem participation

Since $SKULL has no supply cap, the token continues to be minted as long as Loot Survivor is played. This means the upgrade economy grows alongside the player base — more players means more kills, more $SKULL, and more competition in Summit.


## Stats

Understanding and optimizing your adventurer's stats is crucial for survival in Loot Survivor. Each of the seven core stats plays a vital role in different aspects of gameplay, from combat effectiveness to market efficiency. Master stat allocation to create powerful builds tailored to your playstyle!

### Stats Overview

<div style={{ background: '#1a2332', padding: '1.5rem', borderRadius: '8px', border: '2px solid #3b82f6', margin: '2rem 0', lineHeight: '1.8' }}>
  <div style={{ marginBottom: '1rem' }}>
    Every adventurer has **7 core stats** that define their capabilities:
  </div>

  <div style={{ marginBottom: '1rem' }}>
    * **Physical Stats**: Strength, Dexterity, Vitality
    * **Mental Stats**: Intelligence, Wisdom, Charisma
    * **Metaphysical**: Luck (special stat with unique mechanics)
  </div>

  <div style={{ marginBottom: '1rem' }}>
    Each Adventurer starts with 12 random stat points.
  </div>

  > **📈 Progression Note:** You gain 1 stat point per level to allocate freely, except for Luck which can only be increased through items!
</div>

### The Seven Core Stats

#### Physical Stats

##### 💪 Strength (STR)

* **Effect:** +10% attack damage per point
* **Formula:** `Damage = Base × (1 + STR/10)`
* Each point increases damage output by 10% with linear scaling and no cap
* Works with all weapon types
* **⚔️ Tip:** 10 STR = double damage!

##### 🏃 Dexterity (DEX)

* **Effect:** Improves flee success rate
* **Formula:** `Success% = (DEX / Level) × 100`
* Flee success depends on DEX/Level ratio
* Keep DEX equal to level for guaranteed escapes
* **🏃 Tip:** DEX = Level = 100% escape!

##### ❤️ Vitality (VIT)

* **Effect:** +15 HP per point (instant heal)
* **Formula:** `Max HP = 100 + (VIT × 15)`
* Increases maximum and current health
* Base health is 100 HP
* **Maximum health cap: 1023 HP**
* **🛡️ Tip:** VIT upgrades heal instantly!

#### Mental Stats

##### 🧠 Intelligence (INT)

* **Effect:** Avoids obstacle damage
* **Formula:** `Avoidance% = (INT / Level) × 100`
* Obstacle avoidance based on INT/Level ratio
* Keep INT equal to level for full immunity
* **🧠 Tip:** INT = Level = No obstacle damage!

##### 📚 Wisdom (WIS)

* **Effect:** Prevents ambush penalties
* **Formula:** `Evasion% = (WIS / Level) × 100`
* Avoids surprise attack penalties
* Also improves exploration rewards
* **👁️ Tip:** Avoids penalties, not the fight!

##### 😎 Charisma (CHA)

* **Effect:** Market discounts
* **Prices:** -1 gold/point for items, -2 gold/point for potions (min 1 gold)
* **Example:** 10 CHA = 10g off items, 20g off potions
* Makes late-game shopping nearly free
* **💰 Tip:** High CHA = nearly free shopping!

#### Metaphysical Stat

##### 🍀 Luck (LUCK)

* **The Special Stat** - Cannot be upgraded with points, only through equipment!
* **Effect:** Critical hit chance & better loot
* **Formula:** `Crit Chance = LUCK%` (caps at 100)
* **Critical Damage:** 2× base damage when triggered
* Determines critical hit probability and improves item discovery
* Get LUCK from jewelry items
* **🎰 Tip:** Stack jewelry for guaranteed crits!

<div
  style={{
backgroundColor: "rgba(239, 68, 68, 0.1)",
border: "1px solid #ef4444",
borderRadius: "6px",
padding: "1rem",
marginTop: "1rem",
fontSize: "0.9rem"
}}
>
  <strong style={{ color: "#ef4444" }}>⚠️ Warning:</strong> Dropping jewelry will remove LUCK stats equal to the greatness level of the item dropped!
</div>

***

### Suffix Boosts & Item Management

<div
  style={{
backgroundColor: "rgba(168, 85, 247, 0.1)",
border: "2px solid #a855f7",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#a855f7" }}>🏆 Enhanced Items</h3>

  <p style={{ marginBottom: "1rem" }}>
    Items with Greatness 15+ gain powerful <strong>suffix boosts</strong> that provide additional stat bonuses beyond base equipment stats. See the <a href="/lootsurvivor/loot/suffix-boost" style={{ color: "#a855f7" }}>Suffix Boost Guide</a> for complete details on all available bonuses.
  </p>

  <div
    style={{
  backgroundColor: "rgba(239, 68, 68, 0.1)",
  border: "1px solid #ef4444",
  borderRadius: "6px",
  padding: "1rem",
  marginTop: "1rem"
}}
  >
    <h4 style={{ marginTop: 0, marginBottom: "0.75rem", color: "#ef4444" }}>⚠️ Unequipping Items with Suffix Boosts</h4>

    <p style={{ marginBottom: "0.75rem" }}>
      When you unequip items with suffix boosts, <strong>most stat bonuses are immediately removed</strong> from your adventurer. However, there are two important exceptions:
    </p>

    <ul style={{ marginBottom: 0 }}>
      <li style={{ marginBottom: "0.5rem" }}>
        <strong>Vitality (VIT):</strong> Remains active even when the item is in your bag
      </li>

      <li>
        <strong>Charisma (CHA):</strong> Remains active even when the item is in your bag
      </li>
    </ul>
  </div>
</div>

### Conclusion

Stats are the foundation of every successful adventurer in Loot Survivor. Whether you choose to be an unstoppable tank, a glass cannon dealing massive damage, or a nimble escape artist, understanding stat mechanics is key to survival. Remember: there's no single "best" build - the optimal stat distribution depends on your playstyle, the items you find, and your ability to adapt to the dungeon's challenges.

> **🏆 Final Thought:** The best stat allocation is one that keeps you alive and progressing. When in doubt, add VIT!


## Free Games Airdrop

### Overview

The Loot Survivor airdrop provides **free game entries** to eligible NFT holders and community members. These free games give players access to the LS2 Dungeon, which contains **2,258,100 SURVIVOR tokens** distributed as rewards based on gameplay performance.

### How It Works

#### Game-Based Distribution

Instead of receiving SURVIVOR tokens directly, eligible participants receive free game entries to play Loot Survivor. The LS2 Dungeon holds 2,258,100 SURVIVOR tokens that are distributed to players based on their performance:

* **Minimum Level 3**: Must reach at least level 3 to earn tokens
* **Tokens = Level Reached**: Starting at level 3, tokens equal to the level reached
* **Promotion Periods**: 4X tokens during weeks 2-4, 2X tokens after week 4
* **Performance-based rewards**: Higher levels mean more tokens
* **Multiple attempts**: Each free game entry is a new opportunity to earn tokens

#### Example Rewards

**Standard Rate (Week 1):**

* Level 3: 3 tokens
* Level 10: 10 tokens
* Level 25: 25 tokens

**4X Promotion (Weeks 2-4):**

* Level 10: 40 tokens
* Level 25: 100 tokens

**2X Promotion (After Week 4):**

* Level 10: 20 tokens
* Level 25: 50 tokens

### Eligibility Categories

#### NFT Collection Holders

Holders of eligible NFT collections receive free game entries based on their holdings at the snapshot date (August 18th, 2025 at 00:00 UTC). The number of free games is determined by:

* Collection
* Number of NFTs held
* Games Amount multiplier for each collection

[View all eligible collections →](/lootsurvivor/token/eligible-collections)

#### Community Contributors

Active community members earn free games through:

* Early participation in Loot Survivor v1
* Community building and content creation
* Bug reporting and testing
* Protocol development contributions

### Claiming Your Free Games

To claim your free game entries and start earning SURVIVOR tokens:

#### Visit the Claims Portal

Navigate to [claims.lootsurvivor.io](https://claims.lootsurvivor.io) to begin the claim process.

![Eligibility Checker Interface](/docs/lootsurvivor/eligibility-checker.png)
*Enter your wallet address to check your free games allocation*

#### What to Expect

1. **Enter Your Wallet Address** - Input your EVM or Starknet wallet address
2. **View Your Allocation** - See your total free games based on NFT holdings
3. **Connect/Create Controller** - Set up a controller for smooth claims process (can claim for multiple wallets)
4. **Claim Your Games** - Complete the claim for all eligible free games
5. **Start Playing** - Begin your adventure and earn SURVIVOR tokens (within 2 weeks)

![Eligibility Results](/docs/lootsurvivor/eligibility-results.png)
*View your allocation and claim your free games*

<img src="/docs/lootsurvivor/controller-wallets.png" alt="Controller Wallets" style={{width: "50%", margin: "0 auto", display: "block"}} />

*Connect multiple wallets to claim games from different eligible addresses*

#### Wallet Ownership Verification

For wallets that are not controllers (such as hardware wallets or EOA wallets):

1. **Sign a Message** - You'll be prompted to sign a message to prove ownership of your wallet
2. **Verification** - The signature verifies you own the NFTs from the snapshot
3. **Games Sent to Controller** - Once verified, your free games are sent to your controller wallet
4. **Play on Controller** - Use your controller wallet to play and earn SURVIVOR tokens

![Wallet Verification](/docs/lootsurvivor/argent-claim.png)
*Sign a message to verify ownership and claim games to your controller*

The claims portal automatically:

* Verifies your eligibility based on the August 18th, 2025 snapshot
* Calculates your total free games across all eligible collections
* Handles the entire claim process securely
* Provides access to start playing immediately

### Free Games Allocation

#### Calculation Method

Free games are allocated based on:

* **NFT Holdings**: Each eligible NFT grants games based on its collection's multiplier
* **Games Amount**: Collections have different game allocations
* **Total Cap**: Maximum 50 free games per eligible address

#### Distribution Examples

* **Loot Holder**: 5 free games per Loot NFT (capped at 50 total)
* **Pudgy Penguin Holder**: 10 free games per Penguin (capped at 50 total)
* **OGS Discord Role**: 10 free games for verified members
* **Multiple Collections**: Games stack across all eligible holdings (up to 50 max)

### Playing Your Free Games

#### Getting Started

1. Claim your free games at [claims.lootsurvivor.io](https://claims.lootsurvivor.io)
2. Access Loot Survivor gameplay interface
3. Start a new game using a free entry
4. Progress through levels to earn SURVIVOR tokens

#### Earning Tokens

* **Level 1-2**: No token rewards
* **Level 3+**: Earn tokens equal to the level reached (e.g., Level 3 = 3 tokens, Level 20 = 20 tokens)
* **Death**: Game ends, tokens earned are credited based on highest level reached
* **Strategy**: Plan your builds to maximize level progression for more tokens

#### Token Distribution

* When a game ends, a claim button appears
* Click the claim button to receive your earned tokens
* Track your total earnings across all games played

### Important Notes

#### 2-Week Expiration Period

* **Free games expire 2 weeks after the claim window opens**
* Plan your gameplay strategy within this timeframe
* Expired games cannot be recovered or extended
* All eligible addresses have the same expiration deadline

#### Gas Fees

* **All gas fees are covered** through our paymaster
* No ETH required for claiming free games
* No transaction fees for playing games
* Completely free experience from claim to gameplay

#### Fair Play

* Protected by onchain VRF (Verifiable Random Function)
* Anti-bot measures built into the smart contract
* Fully transparent and verifiable gameplay

### Strategy Tips

#### Maximize Your Earnings

* Study optimal builds before playing
* Join community discussions for strategies
* Use your free games before the 2-week window expires

#### Resource Management

* Free games are valuable opportunities
* Each game is a chance at significant token earnings
* Token rewards scale directly with level reached
* Community guides available for gameplay optimization

### Support

For assistance with free games:

* Visit the official documentation
* Join Discord for community strategies
* Check FAQs for common questions
* Submit support tickets for technical issues

### Disclaimer

Free game entries are distributed to reward early supporters and community members. The 2,258,100 SURVIVOR tokens in the LS2 Dungeon are distributed solely based on gameplay performance. Token earnings depend on individual skill and game progression.


## Eligible Collections for Free Games

The following NFT collections are eligible for **free game entries** to Loot Survivor, where players can earn SURVIVOR tokens through gameplay.

### Free Games Distribution

Eligible NFT holders receive free game entries based on their collection holdings at the snapshot date. These free games provide access to the LS2 Dungeon containing 2,000,000 SURVIVOR tokens. Players earn tokens equal to the level they reach (minimum level 3 required).

### Eligible Collections List

| Collection              | Network  | Collection Size | Free Games per NFT | View Contract                                                                                                 |
| ----------------------- | -------- | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------- |
| 1337 Skulls             | Ethereum | 7,331           | 5                  | [Etherscan](https://etherscan.io/address/0x9251dec8df720c2adf3b6f46d968107cbbadf4d4)                          |
| Loot                    | Ethereum | 7,779           | 5                  | [Etherscan](https://etherscan.io/address/0xff9c1b15b16263c61d017ee9f65c50e4ae0113d7)                          |
| Loot Explorers          | Ethereum | 7,998           | 2                  | [Etherscan](https://etherscan.io/address/0x508d06b8f3a4b0fd363239ce61e0c4b0b82f3626)                          |
| The Wild Bunch          | Ethereum | 3,997           | 2                  | [Etherscan](https://etherscan.io/address/0xe9a1a323b4c8fd5ce6842edaa0cd8af943cbdf22)                          |
| BAYC                    | Ethereum | 9,998           | 5                  | [Etherscan](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d)                          |
| Dizzy Dragons           | Ethereum | 9,401           | 2                  | [Etherscan](https://etherscan.io/address/0x882A47e6070acA3f38Ce6929501F4787803A072b)                          |
| Hyperloot               | Ethereum | 8,585           | 2                  | [Etherscan](https://etherscan.io/address/0x0290d49f53a8d186973b82faafdafe696b29acbb)                          |
| LobsterDAO              | Ethereum | 3,546           | 4                  | [Etherscan](https://etherscan.io/address/0x026224a2940bfe258d0dbe947919b62fe321f042)                          |
| Moonbirds               | Ethereum | 9,999           | 4                  | [Etherscan](https://etherscan.io/address/0x23581767a106ae21c074b2276d25e5c3e136a68b)                          |
| Foxy PFP                | Linea    | 10,000          | 2                  | [Lineascan](https://lineascan.build/address/0xe46c02315c4a991d061a06f165028f8c9167249b)                       |
| The Birth Lottery       | Linea    | 666             | 2                  | [Lineascan](https://lineascan.build/address/0xc7e1c28dc11e43ebe93f2664a53ae3775eba68cc)                       |
| Genesis Mana            | Ethereum | 11,535          | 2                  | [Etherscan](https://etherscan.io/address/0xf4b6040a4b1b30f1d1691699a8f3bf957b03e463)                          |
| The Eye for Adventurers | Ethereum | 1,614           | 3                  | [Etherscan](https://etherscan.io/address/0xb8a51862964f77025abb65e2c6a39ee8070c8ed4)                          |
| Genesis Adventurers     | Ethereum | 633             | 5                  | [Etherscan](https://etherscan.io/address/0x8db687aceb92c66f013e1d614137238cc698fedb)                          |
| Terraforms              | Ethereum | 9,911           | 5                  | [Etherscan](https://etherscan.io/address/0x4e1f41613c9084fdb9e34e11fae9412427480e56)                          |
| The Dudes               | Ethereum | 512             | 3                  | [Etherscan](https://etherscan.io/address/0xb0cf7da8dc482997525be8488b9cad4f44315422)                          |
| Crypts and Caverns      | Ethereum | 8,785           | 2                  | [Etherscan](https://etherscan.io/address/0x86f7692569914B5060Ef39aAb99e62eC96A6Ed45)                          |
| Trusta OG Dragons       | Ethereum | 3,707           | 2                  | [Etherscan](https://etherscan.io/address/0xe0e126ce63becbecd72bee4f7673b4e50d5a9965)                          |
| Wandernauts             | Ethereum | 8,887           | 2                  | [Etherscan](https://etherscan.io/address/0x793daf78b74aadf1eda5cc07a558fed932360a60)                          |
| Based Ghouls            | Ethereum | 6,667           | 2                  | [Etherscan](https://etherscan.io/address/0xef1a89cbfabe59397ffda11fc5df293e9bc5db90)                          |
| Pirate Nation           | Ethereum | 9,999           | 3                  | [Etherscan](https://etherscan.io/address/0x1b41d54b3f8de13d58102c50d7431fd6aa1a2c48)                          |
| Grugs Lair              | Ethereum | 1,000           | 1                  | [Etherscan](https://etherscan.io/address/0xfa9ed22ca5d329ecaee9347f72e18c1fc291471b)                          |
| Dope Wars               | Ethereum | 7,999           | 3                  | [Etherscan](https://etherscan.io/address/0x8707276df042e89669d69a177d3da7dc78bd8723)                          |
| Blobert                 | Starknet | 4,844           | 2                  | [Voyager](https://voyager.online/contract/0x00539f522b29ae9251dbf7443c7a950cf260372e69efab3710a11bf17a9599f1) |
| Schizoid                | Starknet | 999             | 3                  | [Voyager](https://voyager.online/contract/0x077485a949c130cf0d98819d2b0749f5860b0734ea28cb678dd3f39379131bfa) |
| FOCG Boi Hands          | Starknet | 39              | 2                  | [Voyager](https://voyager.online/contract/0x02ef78f4031b4250e4ae8c4f0b18af4ef0cbbb405cdb20f80d1041b53aa2f1a1) |
| Brother ID              | Starknet | 2,265           | 2                  | [Voyager](https://voyager.online/contract/0x0212f1c57700f5a3913dd11efba540196aad4cf67772f7090c62709dd804fa74) |
| Realms                  | Starknet | 5,099           | 3                  | [Voyager](https://voyager.online/contract/0x07ae27a31bb6526e3de9cf02f081f6ce0615ac12a6d7b85ee58b8ad7947a2809) |
| Banners (Ethereum)      | Ethereum | 1,785           | 3                  | [Etherscan](https://etherscan.io/address/0x527a4206ac04c2017295cf32f1fc2f9e034a7c40)                          |
| Banners (Starknet)      | Starknet | 9,170           | 2                  | [Voyager](https://voyager.online/contract/0x02d66679de61a5c6d57afd21e005a8c96118bd60315fd79a4521d68f5e5430d1) |
| Wolf Nation             | Starknet | 333             | 3                  | [Voyager](https://voyager.online/contract/0x0413485dbeccec6320d35dcba14375e7ca973f021486496a61286edb958fd861) |
| zKube                   | Starknet | 11,326          | 1                  | [Voyager](https://voyager.online/contract/0x04fd5df500e6c6615e4423258639f189455672bc841ba58f1c781ac7c5ff4bd8) |
| Karats                  | Starknet | 512             | 2                  | [Voyager](https://voyager.online/contract/0x07d8ea58612a5de25f29281199a4fc1f2ce42f0f207f93c3a35280605f3b8e68) |
| Karats 2                | Starknet | 512             | 2                  | [Voyager](https://voyager.online/contract/0x030f694df2a04e04cf3e1d3e79dd5aadfdaa77295bb007696222fc60a5e8730d) |
| Ducks Everywhere        | Starknet | 300             | 10                 | [Voyager](https://voyager.online/contract/0x04fa864a706e3403fd17ac8df307f22eafa21b778b73353abf69a622e47a2003) |
| Pistols                 | Starknet | 126             | 5                  | [Voyager](https://voyager.online/contract/0x014aa76e6c6f11e3f657ee2c213a62006c78ff2c6f8ed40b92c42fd554c246f2) |
| Influence Asteroids     | Starknet | 11,726          | 1                  | [Voyager](https://voyager.online/contract/0x0603cf837055c64d026a3c5a9e3a83036cea6c4a3f68a9e19f7a687d726fe817) |
| Starkurabu              | Starknet | 10,000          | 1                  | [Voyager](https://voyager.online/contract/0x03ab1124ef9ec3a2f2b1d9838f9066f9a894483d40b33390dda8d85c01a315a3) |
| Jokers Of Neon Beasts   | Starknet | 104             | 5                  | [Voyager](https://voyager.online/contract/0x07268fcf96383f8691b91ba758cc8fefe0844146f0557909345b841fb1de042f) |
| Based Punks             | Base     | 5,000           | 2                  | [Basescan](https://basescan.org/address/0xcB28749c24AF4797808364D71d71539bc01E76d4)                           |
| OK Computer             | Base     | 5,000           | 2                  | [Basescan](https://basescan.org/address/0xCE2830932889C7fB5e5206287C43554E673dCc88)                           |
| Blackmirror Experience  | Base     | 7,078           | 2                  | [Basescan](https://basescan.org/address/0x108dB2038C6e8Bc1A0b058c70e752b14d08648BF)                           |
| re:generates            | Base     | 6,665           | 2                  | [Basescan](https://basescan.org/address/0x56dFE6ae26bf3043DC8Fdf33bF739B4fF4B3BC4A)                           |
| Writ of Passage         | Arbitrum | 10,000          | 2                  | [Arbiscan](https://arbiscan.io/address/0x5d541B55763A9277f61a739f40B6021A16C2d3d8)                            |
| Liberty Cats            | Polygon  | 7,777           | 2                  | [Polygonscan](https://polygonscan.com/address/0x0030F47D6a73Bc518CF18fE027Ea91DD6B2b6003)                     |
| Billions Genesis        | Polygon  | 2,999           | 2                  | [Polygonscan](https://polygonscan.com/address/0xeCb63be05886749De33709835e824AEFcFd74f8F)                     |
| Pudgy Penguins          | Ethereum | 8,888           | 10                 | [Etherscan](https://etherscan.io/address/0xBd3531dA5CF5857e7CfAA92426877b022e612cf8)                          |
| The Larp Collective     | Arbitrum | 420             | 2                  | [Arbiscan](https://arbiscan.io/address/0x48D2c1716DFDF8aDd5a5EA658c460e7257448660)                            |
| ZTX Genesis Homes       | Arbitrum | 3,999           | 2                  | [Arbiscan](https://arbiscan.io/address/0x35373efc2FD7D852729cae869Cc32acc979100bD)                            |
| Forgotten Runes         | Ethereum | 10,000          | 3                  | [Etherscan](https://etherscan.io/address/0x521f9c7505005cfa19a8e5786a9c3c9c9f5e6f42)                          |
| Cool Cats               | Ethereum | 10,000          | 3                  | [Etherscan](https://etherscan.io/address/0x1a92f7381b9f03921564a437210bb9396471050c)                          |
| Bankr                   | Base     | 1,000           | 10                 | [Basescan](https://basescan.org/address/0x9fab8c51f911f0ba6dab64fd6e979bcf6424ce82)                           |
| Mee6 Genesis Pass       | Ethereum | 4,444           | 3                  | [Etherscan](https://etherscan.io/address/0xe9ab13482aeab3727e976257d8e1f026e12e9ecd)                          |
| Adventurers             | Starknet | 10,638          | 1                  | [Voyager](https://voyager.online/contract/0x018108b32cea514a78ef1b0e4a0753e855cdf620bc0565202c02456f618c4dc4) |
| OGS Discord Role        | Starknet | -               | 10                 | Discord Verified                                                                                              |

### Understanding Free Games

#### How Free Games Work

The "Free Games per NFT" column shows how many free game entries each NFT from that collection grants. For example:

* Owning 1 Loot NFT = 5 free games
* Owning 2 Pudgy Penguins = 20 free games (10 per NFT)
* Holding multiple eligible NFTs = Games stack across all collections
* **Maximum 50 free games per address** regardless of total holdings

#### Token Earning Potential

Each free game is an opportunity to earn SURVIVOR tokens through gameplay:

* **Level 1-2**: No rewards (warm-up levels)
* **Level 3+**: Earn tokens equal to the level reached
* **Example**: Reaching level 3 earns 3 tokens, level 25 earns 25 tokens, level 50 earns 50 tokens

#### Multi-Chain Support

Eligible collections span multiple networks:

* **Ethereum** - The majority of legacy collections
* **Starknet** - Native Loot Survivor ecosystem collections
* **Base** - Emerging gaming communities
* **Arbitrum** - L2 gaming collections
* **Polygon** - Alternative L2 collections
* **Linea** - Next-generation gaming projects

### Collection Categories

#### Premium Allocations (10+ games)

Collections receiving the highest free game allocations:

* **Pudgy Penguins**: 10 games per NFT
* **Ducks Everywhere**: 10 games per NFT
* **Bankr**: 10 games per NFT
* **OGS Discord Role**: 10 games for verified members

#### Loot Ecosystem (5 games)

Original Loot-related collections with enhanced allocations:

* **Loot**: 5 games per NFT
* **Genesis Adventurers**: 5 games per NFT
* **1337 Skulls**: 5 games per NFT
* **BAYC**: 5 games per NFT
* **Terraforms**: 5 games per NFT

#### Standard Gaming Collections (2-4 games)

Most collections receive standard allocations:

* **2 games**: Common allocation for gaming NFTs
* **3 games**: Enhanced allocation for active communities
* **4 games**: Premium allocation for key partners

#### Entry Level (1 game)

Collections with base-level allocations:

* **Grugs Lair**: 1 game per NFT
* **Influence Asteroids**: 1 game per NFT
* **Starkurabu**: 1 game per NFT
* **Adventurers**: 1 game per NFT
* **zKube**: 1 game per NFT

### Snapshot Details

The eligibility snapshot was taken on **August 18th, 2025 at 00:00 UTC**. All NFT holdings and free game allocations are based on ownership at this specific point in time.

### Verification Process

To verify your free games allocation:

1. Check your NFT holdings as of August 18th, 2025 at 00:00 UTC
2. Calculate total free games: (NFTs held × Free Games per NFT)
3. Sum across all eligible collections you held
4. Apply the 50 free games per address maximum cap
5. Connect wallet to claim interface for automatic calculation

### Important Notes

* **Maximum 50 free games per eligible address**
* **Free games expire 2 weeks after the claim window opens** - Same deadline for all players
* Multiple NFTs from the same collection grant cumulative games (up to the 50 game cap)
* Transfers after the snapshot do not affect eligibility
* The OGS Discord Role requires Discord verification, not on-chain holdings
* Strategic gameplay can maximize token earnings from free games


## SURVIVOR Token

The SURVIVOR token is the native governance and economic coordination token for Loot Survivor, designed to decentralize the ownership role of the game contracts and promote the growth of the Loot Survivor ecosystem.

### Overview

* Total Supply: 10,000,000
* Distribution: 75% Community; 25% Team
* Lockups: None
* Contract: [`0x042dd777885ad2c116be96d4d634abc90a26a790ffb5871e037dd5ae7d2ec86b`](/lootsurvivor/contracts#governance-contracts)

### Purpose

SURVIVOR is the governance and economic coordination token for Loot Survivor.

Governance: SURVIVOR lets holders propose and vote on specific onchain parameters (e.g., which Dungeon the Beasts inhabit, royalty settings for the Beast NFT collection, Beast Mode settings, which ERC‑20s the Dungeon accepts, and the Dungeon’s payment token).

Autonomous treasury growth: When a player buys a Dungeon Ticket, immutable code automatically uses 80% of that payment to purchase SURVIVOR on a decentralized exchange and deposits the purchased tokens into the Survivor Treasury, which is governed by SURVIVOR holders.

No promises / no rights to payouts: SURVIVOR does not grant rights to profits, revenue, dividends, or distributions. The automated purchases are a mechanical feature of the contracts, not a commitment to support price or provide returns.

### Key Features

#### Decentralized Ownership Role

The SURVIVOR token ships with a fully onchain governance system, built on top of [OpenZeppelin’s audited governance components](https://docs.openzeppelin.com/contracts-cairo/2.0.0/governance). The governance system enables SURVIVOR token holders to express their will onchain and for their shared will to execute as an onchain transaction. This allows sensitive, configurable game settings,such as which Dungeon the Beasts are in, to be truly owned and controllable by the community instead of the developers.

The Survivor Governance Contract will control the following settings:

* [Beast NFT](https://voyager.online/nft-contract/0x0280ace0b2171106eaebef91ca9b097a566108e9452c45b94a7924a9f794ae80):
  * Move Beasts to a new Dungeon
  * Change royalty information (default: 5% distributed to the Survivor Treasury)
* [LS2 Beast Mode](https://voyager.online/contract/0x02fb722c25768e4a9994258754e7103895fd2f33cbcc1edc8711807950830cb5):
  * Change Beast Mode settings
  * Add and remove ERC‑20s from the Dungeon
  * Change the payment token for the Dungeon

#### Economic Coordination

To support the sustainable growth of the Loot Survivor ecosystem, Loot Survivor ships with an autonomous and immutable SURVIVOR buy‑back mechanism. 80% of the proceeds from the sale of Dungeon Tickets, which are required to enter the Dungeon and collect Beasts, are used to purchase SURVIVOR tokens using Ekubo’s TWAMM and to deposit them into the Survivor Treasury. The remaining 20% is distributed to $veLORDS holders for the benefit of Bibliotheca DAO, the original incubator of Loot Survivor.

#### Treasury Bootstrap

The treasury is initially seeded with 1M SURVIVOR and approximately 3M LORDS at genesis.

#### SURVIVOR Sale (Programmatic DCA via TWAMM):

* Supply: 15% of total supply.
* Method: A 3‑month programmatic DCA order via TWAMM (Oct 15 – Jan 15).
* Proceeds: 100% contributed to the community treasury for ecosystem growth as governed onchain.

DISCLAIMERS: This sale is programmatic, there are no allocations, discounts, or price/return statements.

#### Community Allocation

75% of the total supply is allocated to the community through various distribution mechanisms, ensuring broad ownership and aligned incentives. Allocations include:

* 22.5% LS2 Dungeon claim allocations (FCFS)
  * 1 Token per level starting at level 3
  * 4X Promotion for games played during weeks 2-4
  * 2X Promotion after week 4 till all tokens are claimed.
* 15% treasury bootstrap DCA
* 10% Survivor Treasury
* 9.3% Beast Entitlements (claim at mint)
* 6.6% LS1/LS1.5 Players
* 5% Loot Realms; 2.5% Loot; 1.5% 1337 Skulls; 1% Genesis Project; 1% Tournaments; 1% Beast Games

Note: NFT royalties, if any, are not guaranteed across marketplaces.

#### Free Games Airdrop

Loot Survivor launches with a two‑week launch promotion that makes \~500k free games available to \~80k addresses across Ethereum, Arbitrum, Base, Starknet, Abstract, Linea, and Polygon. Those holding select NFTs on these platforms will be able to claim free games (including gas), allowing them to play Loot Survivor and collect Beasts and SURVIVOR tokens.

### Quick Links

* [Tokenomics](/lootsurvivor/token/tokenomics) - Detailed breakdown of token distribution and allocations
* [Airdrop](/lootsurvivor/token/airdrop) - How to claim your SURVIVOR tokens and eligibility criteria
* [Eligible Collections](/lootsurvivor/token/eligible-collections) - NFT collections eligible for free games

### Security

Governance contracts use well‑known OpenZeppelin components. This is not a security audit; no system is risk‑free.
Game contracts are cutting‑edge and unaudited; use at your own risk.

### Disclaimers

The SURVIVOR token is designed to decentralize ownership and governance of the Loot Survivor protocol. It represents participation rights in the ecosystem and should not be considered a financial investment.

What SURVIVOR is not: SURVIVOR is not equity or debt. Automated purchases into the treasury are mechanical contract behavior, not price support or an offer of returns. Participation involves smart‑contract risk, market volatility, and governance outcomes that may not align with your preferences. Users should understand these risks before participating. Nothing here is investment advice.


## Tokenomics

### Total Supply

The total supply of the SURVIVOR token is **10,000,000** tokens, distributed between community and team allocations to ensure sustainable growth and development of the Loot Survivor ecosystem.

### Distribution Overview

| Category             | Tokens         | Percentage | Description                         |
| -------------------- | -------------- | ---------- | ----------------------------------- |
| **Community**        | **7,500,000**  | **75%**    |                                     |
| LS2 Dungeon          | 2,258,100      | 22.58%     | Gameplay rewards                    |
| Treasury DCA         | 1,500,000      | 15%        | 3-month programmatic sale via TWAMM |
| Survivor Treasury    | 1,002,222      | 10.02%     | DAO-controlled treasury             |
| Beast Entitlements   | 931,500        | 9.32%      | Claim at Beast mint                 |
| Biblio (Loot Realms) | 500,000        | 5%         | DAO Sponsor                         |
| Legacy Beast Bonus   | 332,028        | 3.32%      | LS1 Beast holder rewards            |
| Top 1k LS1.5 Players | 326,150        | 3.26%      | Top player rewards                  |
| Loot                 | 250,000        | 2.5%       | DAO Sponsor                         |
| 1337 Skulls          | 150,000        | 1.5%       | 1337 Skulls                         |
| Genesis Project      | 100,000        | 1%         | DAO Sponsor                         |
| Budokan              | 100,000        | 1%         | Tournament Rewards                  |
| Summit               | 100,000        | 1%         | Beast Game Rewards                  |
| **Team**             | **2,500,000**  | **25%**    | No lockups                          |
| **Total**            | **10,000,000** | **100%**   |                                     |

### Distribution Breakdown

#### Community Allocation: 7,500,000 (75%)

The majority of SURVIVOR tokens are allocated to the community through various mechanisms designed to reward participation, contribution, and loyalty to the ecosystem.

##### LS2 Dungeon Rewards: 2,258,100 (22.58%)

* First-come, first-served distribution through gameplay
* Tokens equal to the level reached (starting at level 3)
* **4X Promotion**: Weeks 2-4 (multiply token rewards by 4)
* **2X Promotion**: After week 4 until all tokens claimed (multiply token rewards by 2)

##### Treasury Bootstrap DCA: 1,500,000 (15%)

* 3-month programmatic DCA order via TWAMM (Oct 15 - Jan 15)
* 100% of proceeds contributed to community treasury
* Ensures fair price discovery and broad distribution

##### Survivor Treasury: 1,002,222 (10.02%)

* DAO-controlled treasury for ecosystem development
* Initial seed funding at genesis
* Governed by SURVIVOR token holders

##### Beast Entitlements: 931,500 (9.32%)

* Auto-claimed with each Beast mint (average 10 tokens per Beast)
* Tier-based distribution:
  * T1 Beasts: 14 tokens per mint
  * T2 Beasts: 12 tokens per mint
  * T3 Beasts: 10 tokens per mint
  * T4 Beasts: 8 tokens per mint
  * T5 Beasts: 6 tokens per mint

##### Legacy Players: 658,178 (6.58%)

* **Legacy Beast Bonus**: 332,028 (3.32%)
  * LS1 Beasts (2,306 total): 249,048 tokens (108 per Beast)
  * LS1.5 Beasts: 82,980 tokens (36 per Beast)
* **Top 1k LS1.5 Players**: 326,150 (3.26%) - Top player rewards

##### Ecosystem Allocations: 1,150,000 (11.5%)

* **Biblio (Loot Realms)**: 500,000 (5%) - Realms ecosystem development
* **Loot**: 250,000 (2.5%) - Distributed to multisig of trusted Loot ecosystem entities
* **1337 Skulls**: 150,000 (1.5%) - Distributed to multisig of trusted Skulls ecosystem entities
* **Genesis Project**: 100,000 (1%) - Distributed to multisig of trusted Genesis ecosystem entities
* **Budokan**: 100,000 (1%) - Player incentives for game-agnostic tournament platform
* **Summit**: 100,000 (1%) - Player incentives and utility for Beasts collected in Loot Survivor

#### Team Allocation: 2,500,000 (25%)

Reserved for the Loot Survivor team. This allocation aligns long-term incentives between the team and the ecosystem's success.

### Value Accrual Mechanisms

#### Governance Treasury

SURVIVOR token holders control the governance treasury, which consists of:

* Proceeds from the Treasury Bootstrap DCA (1.5M tokens sold over 3 months)
* 80% of proceeds from dungeon ticket purchases
* 1,002,222 SURVIVOR tokens from the Survivor Treasury allocation
* Initial seed of \~3M LORDS at genesis

These funds can be directed towards:

* Buyback and burns to distribute game revenue to token holders
* Development funding for new features
* Liquidity provision incentives
* Ecosystem partnerships and growth initiatives

#### Governance Rights

SURVIVOR token holders control:

* **Beast NFT Settings**:
  * Move Beasts to new Dungeons
  * Royalty settings (default 5% to Survivor Treasury)
* **LS2 Beast Mode**:
  * Beast Mode configuration
  * ERC-20 acceptance in Dungeons
  * Dungeon payment token selection
* **Treasury Management**:
  * Allocation of treasury funds
  * Partnership approvals and funding
  * Community initiative funding

### Distribution Schedule

#### Launch Distributions

* **Free Games Airdrop**: \~500k games to \~80k addresses (2-week claim window)
* **Beast Entitlements**: Claimable at Beast mint
* **LS1/LS1.5 Players**: Based on historical participation

#### Ongoing Distributions

* **LS2 Dungeon**: First-come, first-served through gameplay
  * Week 1: Standard rate (tokens = level reached, starting at L3)
  * Weeks 2-4: 4X promotion (standard rate × 4)
  * After Week 4: 2X promotion until exhausted (standard rate × 2)
* **Treasury Bootstrap DCA**: 3-month programmatic sale (Oct 15 - Jan 15)

#### No Lockups

* All allocations are immediately liquid upon receipt
* No vesting schedules or lockup periods
* Team tokens have no restrictions

### Economic Sustainability

The tokenomics model is designed to create a self-sustaining ecosystem where:

* Players are rewarded for skill and participation
* Developers are incentivized to build on the platform
* Token holders benefit from ecosystem growth
* Protocol revenue supports ongoing development

This balanced approach ensures long-term viability while maintaining decentralization and community ownership.


## Technical Architecture

Loot Survivor is built on Starknet using the Dojo engine, implementing a fully onchain game architecture where all game logic, state management, and randomness are handled by smart contracts.

### Technology Stack

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '1rem', margin: '2rem 0' }}>
  <div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #3b82f6' }}>
    #### ⛓️ Blockchain Layer

    | Component     | Technology     | Version |
    | ------------- | -------------- | ------- |
    | **Network**   | Starknet L2    | Mainnet |
    | **Language**  | Cairo          | 2.10.1  |
    | **Framework** | Dojo           | 1.6.2   |
    | **Standards** | ERC20/721/1155 | Latest  |
  </div>

  <div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #10b981' }}>
    #### 🌐 Frontend Stack

    | Component     | Technology     | Purpose           |
    | ------------- | -------------- | ----------------- |
    | **Framework** | React 18       | UI rendering      |
    | **Language**  | TypeScript     | Type safety       |
    | **Build**     | Vite           | Fast bundling     |
    | **State**     | Zustand        | State management  |
    | **Styling**   | Tailwind + MUI | Responsive design |
  </div>

  <div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #a855f7' }}>
    #### 🏭 Infrastructure

    | Service     | Provider   | Purpose           |
    | ----------- | ---------- | ----------------- |
    | **Indexer** | Torii      | Event indexing    |
    | **RPC**     | Starknet   | Blockchain access |
    | **Storage** | IPFS       | Asset storage     |
    | **CDN**     | Cloudflare | Global delivery   |
  </div>
</div>

#### Frontend Stack

* **Framework**: React 18 with TypeScript
* **Build Tool**: Vite
* **State Management**: Zustand
* **Styling**: Tailwind CSS + Material-UI
* **Wallet Integration**: StarknetKit + Cartridge Controller

#### Infrastructure

* **Indexer**: Torii (Dojo's indexer)
* **RPC**: Starknet full nodes
* **Storage**: IPFS for assets
* **CDN**: Cloudflare for static assets

### System Architecture

#### High-Level Overview

```
┌─────────────────────────────────────────────────────────────┐
│                         Frontend (React)                      │
├─────────────────────────────────────────────────────────────┤
│                     StarknetKit / Cartridge                   │
├─────────────────────────────────────────────────────────────┤
│                          Torii Indexer                        │
├─────────────────────────────────────────────────────────────┤
│                      Dojo Framework (ECS)                     │
├─────────────────────────────────────────────────────────────┤
│                    Cairo Smart Contracts                      │
├─────────────────────────────────────────────────────────────┤
│                         Starknet L2                           │
└─────────────────────────────────────────────────────────────┘
```

#### Component Architecture

##### Smart Contract Layer

The contract architecture follows a modular system design:

```
contracts/
├── systems/
│   ├── adventurer/     # Player character logic
│   ├── beast/          # Enemy AI and combat
│   ├── game/           # Core game loop
│   ├── loot/           # Item generation
│   ├── market/         # Trading system
│   └── settings/       # Configuration
├── models/
│   ├── adventurer/     # Character data structures
│   ├── beast.cairo     # Beast entities
│   ├── combat.cairo    # Combat state
│   ├── loot.cairo      # Item models
│   └── market.cairo    # Market state
└── libs/
    ├── game.cairo      # Game utilities
    └── settings.cairo  # Config helpers
```

##### Frontend Architecture

```
client/src/
├── desktop/           # Desktop-optimized UI
│   ├── components/   # Reusable components
│   ├── overlays/     # Screen overlays
│   └── pages/        # Route pages
├── mobile/           # Mobile-optimized UI
│   ├── components/   # Mobile components
│   ├── containers/   # Screen containers
│   └── pages/        # Mobile routes
├── dojo/             # Blockchain integration
│   ├── useSystemCalls.ts    # Contract interactions
│   ├── useGameSettings.ts   # Settings hooks
│   └── useQuests.ts         # Quest system
├── stores/           # Zustand state management
│   ├── gameStore.ts # Game state
│   ├── marketStore.ts # Market state
│   └── uiStore.ts    # UI state
└── generated/        # Auto-generated bindings
```

### Data Models

#### Entity-Component System (ECS)

Dojo uses an ECS architecture where:

* **Entities**: Unique identifiers (adventurer ID, beast ID)
* **Components**: Data containers (stats, equipment, position)
* **Systems**: Logic processors (combat, movement, trading)

#### Core Entities

<div style={{ background: '#0a0a0a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #333', margin: '1rem 0' }}>
  ##### 🧿 Adventurer Entity

  ```cairo
  pub struct Adventurer {
      pub health: u16, // 10 bits
      pub xp: u16, // 15 bits
      pub gold: u16, // 9 bits
      pub beast_health: u16, // 10 bits
      pub stat_upgrades_available: u8, // 4 bits
      pub stats: Stats, // 30 bits - 7 core attributes
      pub equipment: Equipment, // 128 bits - 8 gear slots
      pub item_specials_seed: u16, // 16 bits
      pub action_count: u16,
  }
  ```

  > **💡 Storage Optimization:** Entire adventurer state packed into a single storage slot!
</div>

##### Beast Entity

```cairo
struct Beast {
    id: u32,
    beast_type: BeastType,
    level: u8,
    health: u16,
    damage: u16,
    special_abilities: Array<Ability>,
}
```

##### Item Entity

```cairo
struct Item {
    id: u32,
    item_type: ItemType,
    tier: Tier,
    level: u8,
    prefix: Option<Prefix>,
    suffix: Option<Suffix>,
    greatness: u8,
}
```

#### State Management

##### Onchain State

* **Persistent**: Adventurer data, items, achievements
* **Session**: Current combat, market seed, active quests
* **Global**: Leaderboards, statistics, events

##### Client State

```typescript
interface GameState {
  adventurer: Adventurer | null;
  currentBeast: Beast | null;
  market: MarketItem[];
  combatLog: CombatEvent[];
  isLoading: boolean;
}
```

### Smart Contract Systems

#### Game System

Central orchestrator managing game flow:

* Action validation
* State transitions
* Event emission
* Gas optimization

#### Adventurer System

Handles player character logic:

* Stat management
* Equipment handling
* Level progression
* Health/death mechanics

#### Combat System

Manages battle mechanics:

* Damage calculation
* Type advantages
* Critical hits
* Flee mechanics

#### Loot System

Generates and manages items:

* Deterministic generation
* Tier distribution
* Prefix/suffix assignment
* Item evolution

#### Market System

Handles trading mechanics:

* Seed-based generation
* Price calculation
* Inventory rotation
* Transaction processing

### Network Architecture

#### Transaction Flow

1. **User Action**: Player initiates action in UI
2. **Wallet Signing**: Transaction signed via wallet
3. **Contract Execution**: Cairo contract processes logic
4. **State Update**: Dojo updates entity state
5. **Event Emission**: Events logged onchain
6. **Indexer Update**: Torii indexes new state
7. **UI Update**: Frontend reflects changes

#### Gas Optimization

##### Packed Storage

```cairo
// Efficient packing of multiple values
struct PackedStats {
    // All stats in single felt252
    packed: felt252,
}
```

##### Batch Operations

```cairo
// Multiple actions in single transaction
fn batch_actions(actions: Array<Action>) {
    // Process all actions together
}
```

### Integration Points

#### Wallet Integration

##### StarknetKit Connection

```typescript
const { connect, connectors } = useStarknet();

// Available connectors
const wallets = [argentX(), braavos(), cartridge()];
```

#### RPC Integration

##### Contract Calls

```typescript
// Read operations (free)
const adventurer = await contract.get_adventurer(id);

// Write operations (gas required)
const tx = await contract.attack_beast();
```

#### Event System

##### Event Structure

```cairo
#[event]
struct BeastSlain {
    adventurer_id: u256,
    beast_id: u32,
    gold_earned: u16,
    xp_earned: u32,
}
```

##### Event Listening

```typescript
contract.on("BeastSlain", (event) => {
  updateGameState(event);
});
```

### Randomness Architecture

#### Deterministic Randomness

Default mode using blockchain data:

```cairo
fn get_random_seed() -> felt252 {
    let info = get_block_info().unbox();
    pedersen(info.block_number, info.block_timestamp)
}
```

#### VRF Integration

Optional true randomness:

```cairo
fn request_random() -> u256 {
    let vrf = IVRFProvider::new();
    vrf.request_random(callback)
}
```

### Security Architecture

<div style={{ background: '#2a1a1a', padding: '1.5rem', borderRadius: '8px', border: '2px solid #dc2626', margin: '1rem 0' }}>
  #### 🔐 Access Control

  ```cairo
  #[external(v0)]
  fn admin_action() {
      assert(get_caller_address() == ADMIN, 'Not authorized');
      // Admin logic
  }
  ```

  | Security Layer       | Protection             | Implementation        |
  | -------------------- | ---------------------- | --------------------- |
  | **Access Control**   | Role-based permissions | Owner/Admin checks    |
  | **Input Validation** | Parameter sanitization | Assert statements     |
  | **Reentrancy Guard** | Attack prevention      | Lock mechanisms       |
  | **Integer Overflow** | Math safety            | Cairo built-in checks |

  > **⚠️ Security Note:** All contracts audited by \[Auditor Name] in \[Date]
</div>

#### Input Validation

```cairo
fn validate_action(action: Action) {
    assert(action.is_valid(), 'Invalid action');
    assert(has_resources(), 'Insufficient resources');
}
```

#### Reentrancy Protection

```cairo
mod ReentrancyGuard {
    fn start() {
        assert(!is_locked(), 'Reentrant call');
        set_locked(true);
    }

    fn end() {
        set_locked(false);
    }
}
```

### Performance Optimization

#### Frontend Optimization

##### Code Splitting

```typescript
const GamePage = lazy(() => import("./pages/GamePage"));
const MarketPage = lazy(() => import("./pages/MarketPage"));
```

##### State Management

```typescript
// Zustand with persistence
const useGameStore = create(
  persist(
    (set) => ({
      // Minimal state updates
    }),
    { name: "game-storage" }
  )
);
```

#### Contract Optimization

##### Storage Patterns

```cairo
// Use packed structs
// Minimize storage writes
// Batch operations
```

##### Computation Optimization

```cairo
// Precompute values
// Use lookup tables
// Minimize loops
```

### Deployment Architecture

#### Environment Configuration

##### Development

```toml
[environment]
rpc_url = "http://localhost:5050"
account_address = "0xDEV"
private_key = "0xDEV_KEY"
```

##### Production

```toml
[environment]
rpc_url = "https://starknet-mainnet.public.blastapi.io"
account_address = "0xPROD"
private_key = "$PROD_KEY"
```

#### Contract Deployment

##### Using Dojo CLI

```bash
# Build contracts
sozo build

# Deploy to network
sozo deploy --world 0xWORLD_ADDRESS

# Verify deployment
sozo inspect
```

#### Frontend Deployment

##### Build Process

```bash
# Install dependencies
pnpm install

# Build for production
pnpm build

# Deploy to CDN
pnpm deploy
```

### Monitoring and Analytics

#### Onchain Metrics

* Transaction volume
* Active players
* Gas usage
* Error rates

#### Application Metrics

* Page load times
* API latencies
* User engagement
* Error tracking

#### Performance Monitoring

```typescript
// Performance tracking
performance.mark("action-start");
await performAction();
performance.mark("action-end");
performance.measure("action", "action-start", "action-end");
```

### Scaling Considerations

#### Horizontal Scaling

* Multiple RPC endpoints
* Load balancing
* CDN distribution
* Regional deployments

#### Vertical Scaling

* Optimized contracts
* Efficient indexing
* Caching strategies
* Database optimization

### Future Architecture

#### Planned Enhancements

##### Multi-chain Support

* Ethereum L1 integration
* Cross-chain bridges
* Multi-network deployment

##### Advanced Features

* Multiplayer dungeons
* Guild systems
* Tournament infrastructure
* Achievement system

##### Technical Improvements

* ZK proof integration
* Advanced VRF
* State channels
* Optimistic updates

### Development Workflow

#### Local Development

1. Start local Starknet node
2. Deploy contracts locally
3. Run frontend dev server
4. Connect to local network

#### Testing Pipeline

1. Unit tests (Cairo)
2. Integration tests
3. Frontend tests
4. E2E tests

#### Deployment Pipeline

1. Code review
2. Automated testing
3. Staging deployment
4. Production release

### Best Practices

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))', gap: '1rem', margin: '2rem 0' }}>
  <div style={{ background: '#1a2332', padding: '1rem', borderRadius: '8px', border: '1px solid #3b82f6' }}>
    #### 📝 Contract Development

    | Practice             | Implementation          |
    | -------------------- | ----------------------- |
    | **Modular Design**   | Separate concerns       |
    | **Gas Optimization** | Pack storage, batch ops |
    | **Testing**          | 90%+ coverage           |
    | **Security**         | Regular audits          |
  </div>

  <div style={{ background: '#1a2a1a', padding: '1rem', borderRadius: '8px', border: '1px solid #10b981' }}>
    #### 🌐 Frontend Development

    | Practice        | Implementation            |
    | --------------- | ------------------------- |
    | **Components**  | Reusable, typed           |
    | **State**       | Minimal, efficient        |
    | **Performance** | Code splitting, lazy load |
    | **Design**      | Mobile-first, accessible  |
  </div>

  <div style={{ background: '#2a1a2a', padding: '1rem', borderRadius: '8px', border: '1px solid #a855f7' }}>
    #### 🔗 Integration Guidelines

    | Practice      | Implementation         |
    | ------------- | ---------------------- |
    | **Errors**    | Graceful handling      |
    | **Retries**   | Exponential backoff    |
    | **Fallbacks** | Degradation paths      |
    | **Feedback**  | Loading states, toasts |
  </div>
</div>

> **🏆 Excellence Standard:** Follow these practices for production-ready code!

### Conclusion

The Loot Survivor architecture demonstrates how complex game mechanics can be implemented fully onchain while maintaining performance and user experience. The modular design allows for easy extension and modification, making it an ideal foundation for blockchain gaming.


## Smart Contracts Documentation

This document provides detailed information about the Loot Survivor smart contracts, their interfaces, and how to interact with them.

### Contract Overview

Loot Survivor's smart contracts are written in Cairo and deployed on Starknet. The contracts follow a modular architecture using the Dojo framework's Entity-Component-System (ECS) pattern.

### Core Contracts

#### Game Contract

The main orchestrator managing the entire game flow.

**Address (Mainnet)**: `0xbcb2386436161d8d3afea0a805a8610ab90af5cf5582d866b83e9cb779bef3`

##### Key Functions

##### start\_game

```cairo
fn start_game(
    client_reward_address: ContractAddress,
    weapon_type: WeaponType,
    name: felt252,
    golden_token_id: u256,
    interface_camel: bool
) -> u256
```

* Starts a new adventure
* Returns the adventurer ID
* Requires payment (ETH or LORDS)

##### explore

```cairo
fn explore(adventurer_id: u256, till_beast: bool)
```

* Explores the dungeon
* `till_beast`: Continue until beast encounter if true
* Triggers obstacles and discoveries

##### attack

```cairo
fn attack(adventurer_id: u256, to_the_death: bool)
```

* Attacks the current beast
* `to_the_death`: Fight until death if true
* Calculates damage and rewards

##### flee

```cairo
fn flee(
    adventurer_id: u256,
    to_the_death: bool
)
```

* Attempts to flee from combat
* Success based on Dexterity
* May take damage on failure

##### upgrade

```cairo
fn upgrade(
    adventurer_id: u256,
    stat_upgrades: Stats,
    items_to_purchase: Array<ItemPurchase>
)
```

* Allocates stat points
* Purchases items from market
* Called after leveling up

#### Adventurer Contract

Manages adventurer data and progression.

**Address (Mainnet)**: `0x3befa9c969bf82bbfa0a96374da9f7aab172101298c0ff2611ec8c2fd02692`

##### Data Structures

##### Adventurer

```cairo
struct Adventurer {
    // Identity
    id: u256,
    owner: ContractAddress,
    name: felt252,
    
    // Progression
    level: u8,
    experience: u32,
    
    // Health
    health: u16,
    max_health: u16,
    
    // Resources
    gold: u16,
    
    // Stats
    strength: u8,
    dexterity: u8,
    vitality: u8,
    intelligence: u8,
    wisdom: u8,
    charisma: u8,
    luck: u8,
    
    // Equipment
    weapon: Item,
    chest: Item,
    head: Item,
    waist: Item,
    foot: Item,
    hand: Item,
    neck: Item,
    ring: Item,
    
    // Inventory
    bag: Bag,
    
    // State
    beast_id: u32,
    stat_points_available: u8,
    actions_per_block: u8,
    mutated: bool,
}
```

##### Stats

```cairo
struct Stats {
    strength: u8,
    dexterity: u8,
    vitality: u8,
    intelligence: u8,
    wisdom: u8,
    charisma: u8,
    luck: u8,
}
```

##### Key Functions

##### get\_adventurer

```cairo
fn get_adventurer(adventurer_id: u256) -> Adventurer
```

* Returns full adventurer data
* Read-only function (no gas)

##### get\_adventurer\_stats

```cairo
fn get_adventurer_stats(adventurer_id: u256) -> Stats
```

* Returns just the stats
* Useful for calculations

##### update\_adventurer

```cairo
fn update_adventurer(adventurer: Adventurer)
```

* Internal function
* Updates adventurer state

#### Beast Contract

Handles beast generation and combat.

**Address (Mainnet)**: `0x66744a5847c4459e019511f390ba8a8da53c5d25de8cd4e24e5f3e450c5d038`

##### Data Structures

##### Beast

```cairo
struct Beast {
    id: u32,
    beast_type: BeastType,
    tier: Tier,
    level: u8,
    health: u16,
    starting_health: u16,
    special_abilities: SpecialAbilities,
}
```

##### BeastType Enum

```cairo
enum BeastType {
    // Starter (T5)
    Rat, Gnome, Goblin, Skeleton,
    
    // Common (T4)
    Wolf, Orc, Troll, Zombie,
    DireWolf, Bear, Spider, Ghoul,
    
    // Uncommon (T3)
    Minotaur, Cyclops, Griffin, Vampire,
    Manticore, Phoenix, Dragon, Lich,
    
    // Rare (T2)
    Balrog, Titan, Leviathan, Tarrasque,
    Typhon, Fenrir, Hydra, Colossus,
    
    // Legendary (T1)
    // ... 75 total beasts
}
```

##### Key Functions

##### generate\_beast

```cairo
fn generate_beast(
    seed: felt252,
    adventurer_level: u8
) -> Beast
```

* Creates a new beast encounter
* Level scales with adventurer
* Deterministic based on seed

##### calculate\_damage

```cairo
fn calculate_damage(
    attacker_strength: u8,
    weapon_type: WeaponType,
    beast_type: BeastType,
    is_critical: bool
) -> u16
```

* Calculates combat damage
* Includes type advantages
* Critical hit multiplier

#### Loot Contract

Manages item generation and evolution.

**Address (Mainnet)**: `0x66744a5847c4459e019511f390ba8a8da53c5d25de8cd4e24e5f3e450c5d038`

##### Data Structures

##### Item

```cairo
struct Item {
    id: u32,
    item_type: ItemType,
    tier: Tier,
    slot: Slot,
    
    // Evolution
    level: u8,
    greatness: u8,
    
    // Special properties
    prefix: Option<ItemPrefix>,
    suffix: Option<ItemSuffix>,
    
    // Stats
    damage: u16,
    armor: u16,
    stat_bonuses: Stats,
}
```

##### ItemType Enum

```cairo
enum ItemType {
    // Weapons
    Blade, Bludgeon, Magic,
    
    // Armor
    Cloth, Hide, Metal,
    
    // Accessories
    Ring, Amulet, Pendant,
}
```

##### Tier Enum

```cairo
enum Tier {
    T1, // Legendary (most expensive)
    T2, // Rare
    T3, // Uncommon
    T4, // Common
    T5, // Starter (cheapest)
}
```

##### Key Functions

##### generate\_item

```cairo
fn generate_item(
    seed: felt252,
    slot: Slot,
    tier: Tier
) -> Item
```

* Creates a new item
* Deterministic generation
* Tier affects rarity

##### evolve\_item

```cairo
fn evolve_item(
    item: Item,
    xp_gained: u32
) -> Item
```

* Levels up an item
* Unlocks suffixes at level 15
* Unlocks prefixes at level 20

#### Market Contract

Handles the in-game marketplace.

##### Data Structures

##### Market

```cairo
struct Market {
    seed: felt252,
    items: Array<MarketItem>,
    potion_price: u16,
    refreshed_at: u64,
}
```

##### MarketItem

```cairo
struct MarketItem {
    item: Item,
    price: u16,
    stock: u8,
}
```

##### Key Functions

##### generate\_market

```cairo
fn generate_market(
    seed: felt252,
    adventurer_level: u8,
    charisma: u8
) -> Market
```

* Creates market inventory
* Prices based on charisma
* Refreshes on level up

##### purchase\_item

```cairo
fn purchase_item(
    market: Market,
    item_id: u32,
    adventurer_gold: u16
) -> (Market, u16)
```

* Processes item purchase
* Returns updated market and remaining gold

### Events

#### Combat Events

```cairo
#[event]
struct AttackEvent {
    adventurer_id: u256,
    beast_id: u32,
    damage_dealt: u16,
    damage_taken: u16,
    is_critical: bool,
}

#[event]
struct BeastSlainEvent {
    adventurer_id: u256,
    beast_id: u32,
    beast_type: BeastType,
    gold_earned: u16,
    xp_earned: u32,
    items_dropped: Array<Item>,
}

#[event]
struct FleeAttemptEvent {
    adventurer_id: u256,
    beast_id: u32,
    success: bool,
    damage_taken: u16,
}
```

#### Progression Events

```cairo
#[event]
struct LevelUpEvent {
    adventurer_id: u256,
    new_level: u8,
    stat_points_gained: u8,
}

#[event]
struct ItemLevelUpEvent {
    adventurer_id: u256,
    item_id: u32,
    new_level: u8,
    suffix_unlocked: Option<ItemSuffix>,
    prefix_unlocked: Option<ItemPrefix>,
}
```

#### Market Events

```cairo
#[event]
struct ItemPurchasedEvent {
    adventurer_id: u256,
    item_id: u32,
    price: u16,
}

#[event]
struct MarketRefreshedEvent {
    adventurer_id: u256,
    seed: felt252,
    items_available: u8,
}
```

### Integration Examples

#### Starting a Game

```typescript
// TypeScript/JavaScript
const startGame = async () => {
    const tx = await gameContract.start_game(
        rewardAddress,     // Address for rewards
        WeaponType.Blade,  // Starting weapon
        "Adventurer",      // Name
        0,                 // Golden token ID (0 if none)
        false              // Interface camel case
    );
    
    const receipt = await tx.wait();
    const adventurerId = receipt.events[0].adventurer_id;
    return adventurerId;
};
```

#### Combat Loop

```typescript
const combatLoop = async (adventurerId: bigint) => {
    // Attack until victory or death
    const tx = await gameContract.attack(
        adventurerId,
        true  // to_the_death
    );
    
    await tx.wait();
    
    // Check if adventurer survived
    const adventurer = await adventurerContract.get_adventurer(adventurerId);
    if (adventurer.health === 0) {
        console.log("Game Over!");
    }
};
```

#### Upgrading After Level Up

```typescript
const upgrade = async (adventurerId: bigint) => {
    const statUpgrades = {
        strength: 1,
        dexterity: 0,
        vitality: 0,
        intelligence: 0,
        wisdom: 0,
        charisma: 0,
        luck: 0,
    };
    
    const itemsToPurchase = [
        { item_id: 123, equip: true },
        { item_id: 456, equip: false },
    ];
    
    await gameContract.upgrade(
        adventurerId,
        statUpgrades,
        itemsToPurchase
    );
};
```

### Gas Optimization

#### Batch Operations

```cairo
// Efficient: Single transaction
fn batch_actions(actions: Array<Action>) {
    for action in actions {
        process_action(action);
    }
}

// Inefficient: Multiple transactions
fn single_action(action: Action) {
    process_action(action);
}
```

#### Storage Packing

```cairo
// Packed storage (efficient)
struct PackedAdventurer {
    // Multiple values in single felt252
    packed_stats: felt252,
    packed_equipment: felt252,
}

// Unpacked storage (less efficient)
struct UnpackedAdventurer {
    strength: u8,
    dexterity: u8,
    vitality: u8,
    // ... each stat separate
}
```

### Security Considerations

#### Access Control

All contracts implement access control:

```cairo
#[external(v0)]
fn admin_function() {
    assert_caller_is_admin();
    // Admin logic
}

fn assert_caller_is_admin() {
    let caller = get_caller_address();
    assert(caller == ADMIN_ADDRESS, 'Unauthorized');
}
```

#### Input Validation

All user inputs are validated:

```cairo
fn validate_stat_upgrade(stats: Stats) {
    let total = stats.strength + stats.dexterity + // ...
    assert(total <= available_points, 'Invalid points');
    assert(stats.strength <= MAX_STAT, 'Stat too high');
}
```

#### Reentrancy Protection

Critical functions use reentrancy guards:

```cairo
fn critical_function() {
    assert(!is_locked(), 'Reentrant');
    set_locked(true);
    
    // Function logic
    
    set_locked(false);
}
```

### Testing Contracts

#### Unit Tests

```cairo
#[test]
fn test_combat_damage() {
    let damage = calculate_damage(
        strength: 10,
        weapon_type: WeaponType::Blade,
        beast_type: BeastType::Goblin,
        is_critical: false
    );
    assert(damage > 0, 'Damage should be positive');
}
```

#### Integration Tests

```cairo
#[test]
fn test_full_game_flow() {
    let adventurer_id = start_game(...);
    explore(adventurer_id, false);
    attack(adventurer_id, false);
    upgrade(adventurer_id, ...);
    // Assert final state
}
```

### Contract Addresses

#### Mainnet Contracts

| Contract   | Address                                                             |
| ---------- | ------------------------------------------------------------------- |
| Game       | `0xbcb2386436161d8d3afea0a805a8610ab90af5cf5582d866b83e9cb779bef3`  |
| Adventurer | `0x3befa9c969bf82bbfa0a96374da9f7aab172101298c0ff2611ec8c2fd02692`  |
| Beast      | `0x66744a5847c4459e019511f390ba8a8da53c5d25de8cd4e24e5f3e450c5d038` |
| Loot       | `0x66744a5847c4459e019511f390ba8a8da53c5d25de8cd4e24e5f3e450c5d038` |
| Market     | `0x1e1c477f2ef896fd638b50caa31e3aa8f504d5c6cb3c09c99cd0b72523f07f7` |

#### Testnet Contracts (Sepolia)

| Contract   | Address                          |
| ---------- | -------------------------------- |
| Game       | `0x[TESTNET_GAME_ADDRESS]`       |
| Adventurer | `0x[TESTNET_ADVENTURER_ADDRESS]` |
| Beast      | `0x[TESTNET_BEAST_ADDRESS]`      |
| Loot       | `0x[TESTNET_LOOT_ADDRESS]`       |
| Market     | `0x[TESTNET_MARKET_ADDRESS]`     |

### ABI Documentation

Full ABI specifications are available in the generated files:

* `/contracts/target/dev/[contract_name].contract_class.json`

### Upgradeability

Contracts use the Dojo framework's upgrade system:

```cairo
#[starknet::contract]
mod UpgradeableContract {
    #[external(v0)]
    fn upgrade(new_class_hash: ClassHash) {
        assert_caller_is_admin();
        replace_class_syscall(new_class_hash);
    }
}
```

### Best Practices

#### Reading Contract State

```typescript
// Always use view functions for reading
const adventurer = await contract.get_adventurer(id);
// These are free (no gas)
```

#### Writing to Contracts

```typescript
// Batch operations when possible
const tx = await contract.batch_actions([
    action1,
    action2,
    action3,
]);
// Single transaction = less gas
```

#### Error Handling

```typescript
try {
    const tx = await contract.attack(adventurerId, true);
    await tx.wait();
} catch (error) {
    if (error.message.includes('Dead adventurer')) {
        // Handle game over
    }
}
```

### Conclusion

The Loot Survivor smart contracts provide a robust, gas-efficient foundation for fully onchain gaming. The modular architecture allows for easy extension while maintaining security and performance.


## Integration Guide

This guide explains how to integrate with Loot Survivor, whether you're building a frontend client, creating tools, or extending the game with additional features.

### Quick Start

#### Prerequisites

* Node.js 18+ or your preferred runtime
* Starknet wallet or programmatic account
* Basic understanding of Starknet and Cairo

#### Installation

##### JavaScript/TypeScript

```bash
# Using npm
npm install starknet @dojoengine/core

# Using pnpm
pnpm add starknet @dojoengine/core

# Using yarn
yarn add starknet @dojoengine/core
```

##### Python

```bash
pip install starknet-py
```

### Setting Up Connection

#### Initialize Provider

```typescript
import { Provider, constants } from 'starknet';

// Mainnet
const provider = new Provider({
    sequencer: {
        network: constants.NetworkName.SN_MAIN,
    },
});

// Testnet (Sepolia)
const provider = new Provider({
    sequencer: {
        network: constants.NetworkName.SN_SEPOLIA,
    },
});
```

#### Contract Instances

```typescript
import { Contract } from 'starknet';
import GameABI from './abis/Game.json';
import AdventurerABI from './abis/Adventurer.json';

const GAME_ADDRESS = "0xbcb2386436161d8d3afea0a805a8610ab90af5cf5582d866b83e9cb779bef3";
const ADVENTURER_ADDRESS = "0x3befa9c969bf82bbfa0a96374da9f7aab172101298c0ff2611ec8c2fd02692";

const gameContract = new Contract(GameABI, GAME_ADDRESS, provider);
const adventurerContract = new Contract(AdventurerABI, ADVENTURER_ADDRESS, provider);
```

### Wallet Integration

#### Using StarknetKit

```typescript
import { connect, disconnect } from '@starknet-io/get-starknet';

const connectWallet = async () => {
    const starknet = await connect({
        modalMode: "alwaysAsk",
        modalTheme: "dark",
    });
    
    if (!starknet?.isConnected) {
        throw new Error("Failed to connect wallet");
    }
    
    return starknet;
};
```

#### Using Cartridge Controller

```typescript
import Controller from '@cartridge/controller';

const controller = new Controller({
    policies: [
        {
            target: GAME_ADDRESS,
            method: 'attack',
        },
        {
            target: GAME_ADDRESS,
            method: 'explore',
        },
    ],
    rpc: "https://api.cartridge.gg/x/starknet/mainnet",
});

await controller.connect();
```

### Reading Game State

#### Get Adventurer Data

```typescript
interface Adventurer {
    id: bigint;
    owner: string;
    name: string;
    level: number;
    health: number;
    gold: number;
    experience: number;
    stats: Stats;
    equipment: Equipment;
}

const getAdventurer = async (adventurerId: bigint): Promise<Adventurer> => {
    const result = await adventurerContract.get_adventurer(adventurerId);
    
    return {
        id: result.id,
        owner: result.owner,
        name: result.name,
        level: Number(result.level),
        health: Number(result.health),
        gold: Number(result.gold),
        experience: Number(result.experience),
        stats: parseStats(result.stats),
        equipment: parseEquipment(result.equipment),
    };
};
```

#### Get Current Beast

```typescript
const getCurrentBeast = async (adventurerId: bigint) => {
    const beast = await gameContract.get_current_beast(adventurerId);
    
    if (!beast) return null;
    
    return {
        id: beast.id,
        type: beast.beast_type,
        level: Number(beast.level),
        health: Number(beast.health),
        maxHealth: Number(beast.starting_health),
    };
};
```

#### Get Market Items

```typescript
const getMarketItems = async (adventurerId: bigint) => {
    const market = await gameContract.get_market(adventurerId);
    
    return market.items.map(item => ({
        id: item.id,
        name: item.name,
        type: item.item_type,
        tier: item.tier,
        price: Number(item.price),
        slot: item.slot,
    }));
};
```

### Writing Transactions

#### Starting a Game

```typescript
const startAdventure = async (
    account: Account,
    weaponType: number,
    name: string
) => {
    const tx = await account.execute({
        contractAddress: GAME_ADDRESS,
        entrypoint: 'start_game',
        calldata: [
            account.address,  // reward address
            weaponType,       // 0: Blade, 1: Bludgeon, 2: Magic
            name,            // adventurer name
            0,               // golden token (0 if none)
            0,               // interface camel case (0 for snake)
        ],
    });
    
    const receipt = await provider.waitForTransaction(tx.transaction_hash);
    
    // Extract adventurer ID from events
    const adventurerId = extractAdventurerIdFromEvents(receipt.events);
    return adventurerId;
};
```

#### Combat Actions

```typescript
// Attack beast
const attack = async (
    account: Account,
    adventurerId: bigint,
    tillDeath: boolean = false
) => {
    const tx = await account.execute({
        contractAddress: GAME_ADDRESS,
        entrypoint: 'attack',
        calldata: [
            adventurerId.toString(),
            tillDeath ? 1 : 0,
        ],
    });
    
    return await provider.waitForTransaction(tx.transaction_hash);
};

// Flee from combat
const flee = async (
    account: Account,
    adventurerId: bigint
) => {
    const tx = await account.execute({
        contractAddress: GAME_ADDRESS,
        entrypoint: 'flee',
        calldata: [
            adventurerId.toString(),
            0, // to_the_death
        ],
    });
    
    return await provider.waitForTransaction(tx.transaction_hash);
};
```

#### Exploration

```typescript
const explore = async (
    account: Account,
    adventurerId: bigint,
    tillBeast: boolean = false
) => {
    const tx = await account.execute({
        contractAddress: GAME_ADDRESS,
        entrypoint: 'explore',
        calldata: [
            adventurerId.toString(),
            tillBeast ? 1 : 0,
        ],
    });
    
    return await provider.waitForTransaction(tx.transaction_hash);
};
```

#### Upgrading

```typescript
interface StatUpgrade {
    strength: number;
    dexterity: number;
    vitality: number;
    intelligence: number;
    wisdom: number;
    charisma: number;
    luck: number;
}

interface ItemPurchase {
    item_id: number;
    equip: boolean;
}

const upgrade = async (
    account: Account,
    adventurerId: bigint,
    stats: StatUpgrade,
    items: ItemPurchase[]
) => {
    const calldata = [
        adventurerId.toString(),
        // Stats (must sum to available points)
        stats.strength,
        stats.dexterity,
        stats.vitality,
        stats.intelligence,
        stats.wisdom,
        stats.charisma,
        stats.luck,
        // Items array
        items.length,
        ...items.flatMap(i => [i.item_id, i.equip ? 1 : 0]),
    ];
    
    const tx = await account.execute({
        contractAddress: GAME_ADDRESS,
        entrypoint: 'upgrade',
        calldata,
    });
    
    return await provider.waitForTransaction(tx.transaction_hash);
};
```

### Event Listening

#### Setting Up Event Listeners

```typescript
import { events } from 'starknet';

const subscribeToEvents = (adventurerId: bigint) => {
    // Listen for combat events
    gameContract.on('AttackEvent', (event) => {
        if (event.adventurer_id === adventurerId) {
            console.log('Attack:', {
                damage_dealt: event.damage_dealt,
                damage_taken: event.damage_taken,
                is_critical: event.is_critical,
            });
        }
    });
    
    // Listen for level up
    gameContract.on('LevelUpEvent', (event) => {
        if (event.adventurer_id === adventurerId) {
            console.log('Level Up! New level:', event.new_level);
        }
    });
    
    // Listen for death
    gameContract.on('AdventurerDiedEvent', (event) => {
        if (event.adventurer_id === adventurerId) {
            console.log('Game Over! Final level:', event.level);
        }
    });
};
```

#### Processing Historical Events

```typescript
const getAdventurerHistory = async (adventurerId: bigint) => {
    const events = await provider.getEvents({
        address: GAME_ADDRESS,
        from_block: { block_number: 0 },
        to_block: 'latest',
        keys: [[adventurerId.toString()]],
        chunk_size: 100,
    });
    
    return events.events.map(parseEvent);
};
```

### Using Torii Indexer

#### GraphQL Queries

```typescript
const TORII_URL = "https://api.cartridge.gg/x/lootsurvivor/torii/graphql";

const query = `
    query GetAdventurer($id: String!) {
        adventurer(id: $id) {
            id
            owner
            level
            health
            gold
            experience
            stats {
                strength
                dexterity
                vitality
                intelligence
                wisdom
                charisma
                luck
            }
        }
    }
`;

const fetchAdventurerData = async (adventurerId: string) => {
    const response = await fetch(TORII_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            query,
            variables: { id: adventurerId },
        }),
    });
    
    const data = await response.json();
    return data.data.adventurer;
};
```

#### WebSocket Subscriptions

```typescript
import { createClient } from 'graphql-ws';

const client = createClient({
    url: 'wss://api.cartridge.gg/x/lootsurvivor/torii/ws',
});

const subscription = `
    subscription OnAdventurerUpdate($id: String!) {
        adventurerUpdated(id: $id) {
            id
            level
            health
            gold
        }
    }
`;

client.subscribe(
    {
        query: subscription,
        variables: { id: adventurerId },
    },
    {
        next: (data) => console.log('Update:', data),
        error: (err) => console.error('Error:', err),
        complete: () => console.log('Subscription complete'),
    }
);
```

### Building Custom Frontends

#### React Hook Example

```typescript
import { useState, useEffect } from 'react';

const useAdventurer = (adventurerId: bigint) => {
    const [adventurer, setAdventurer] = useState(null);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState(null);
    
    useEffect(() => {
        const fetchData = async () => {
            try {
                setLoading(true);
                const data = await getAdventurer(adventurerId);
                setAdventurer(data);
            } catch (err) {
                setError(err);
            } finally {
                setLoading(false);
            }
        };
        
        fetchData();
        
        // Set up event listeners
        const unsubscribe = subscribeToAdventurerUpdates(
            adventurerId,
            setAdventurer
        );
        
        return unsubscribe;
    }, [adventurerId]);
    
    return { adventurer, loading, error };
};
```

#### State Management

```typescript
import { create } from 'zustand';

interface GameStore {
    adventurer: Adventurer | null;
    beast: Beast | null;
    market: MarketItem[];
    
    setAdventurer: (adventurer: Adventurer) => void;
    setBeast: (beast: Beast) => void;
    setMarket: (items: MarketItem[]) => void;
    
    attack: () => Promise<void>;
    flee: () => Promise<void>;
    explore: () => Promise<void>;
}

const useGameStore = create<GameStore>((set, get) => ({
    adventurer: null,
    beast: null,
    market: [],
    
    setAdventurer: (adventurer) => set({ adventurer }),
    setBeast: (beast) => set({ beast }),
    setMarket: (market) => set({ market }),
    
    attack: async () => {
        const { adventurer } = get();
        if (!adventurer) return;
        
        const result = await attackBeast(adventurer.id);
        // Update state based on result
    },
    
    // ... other actions
}));
```

### Building Game Tools

#### Leaderboard API

```typescript
const getLeaderboard = async (limit = 100) => {
    const query = `
        query GetLeaderboard($limit: Int!) {
            adventurers(
                orderBy: "level",
                orderDirection: "desc",
                limit: $limit
            ) {
                id
                owner
                name
                level
                gold
                timestamp
            }
        }
    `;
    
    const response = await fetch(TORII_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            query,
            variables: { limit },
        }),
    });
    
    const data = await response.json();
    return data.data.adventurers;
};
```

#### Statistics Tracker

```typescript
const getPlayerStats = async (playerAddress: string) => {
    const query = `
        query GetPlayerStats($owner: String!) {
            adventurers(where: { owner: $owner }) {
                id
                level
                gold
                experience
                timestamp
                died_at
            }
        }
    `;
    
    const response = await fetch(TORII_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            query,
            variables: { owner: playerAddress },
        }),
    });
    
    const data = await response.json();
    
    // Calculate statistics
    const adventures = data.data.adventurers;
    return {
        totalAdventures: adventures.length,
        highestLevel: Math.max(...adventures.map(a => a.level)),
        totalGold: adventures.reduce((sum, a) => sum + a.gold, 0),
        averageLevel: adventures.reduce((sum, a) => sum + a.level, 0) / adventures.length,
    };
};
```

### Error Handling

#### Common Errors

```typescript
const handleGameAction = async (action: () => Promise<any>) => {
    try {
        const result = await action();
        return { success: true, data: result };
    } catch (error) {
        // Handle specific errors
        if (error.message.includes('Adventurer is dead')) {
            return { success: false, error: 'GAME_OVER' };
        }
        if (error.message.includes('Insufficient gold')) {
            return { success: false, error: 'INSUFFICIENT_FUNDS' };
        }
        if (error.message.includes('Invalid stat allocation')) {
            return { success: false, error: 'INVALID_STATS' };
        }
        
        // Generic error
        return { success: false, error: error.message };
    }
};
```

#### Retry Logic

```typescript
const retryWithBackoff = async (
    fn: () => Promise<any>,
    maxRetries = 3,
    delay = 1000
) => {
    for (let i = 0; i < maxRetries; i++) {
        try {
            return await fn();
        } catch (error) {
            if (i === maxRetries - 1) throw error;
            await new Promise(resolve => setTimeout(resolve, delay * (i + 1)));
        }
    }
};
```

### Testing Integration

#### Unit Tests

```typescript
import { describe, it, expect } from 'vitest';

describe('Game Integration', () => {
    it('should start a new game', async () => {
        const adventurerId = await startAdventure(
            mockAccount,
            WeaponType.Blade,
            'Test Hero'
        );
        
        expect(adventurerId).toBeGreaterThan(0n);
    });
    
    it('should handle combat', async () => {
        const result = await attack(mockAccount, adventurerId);
        expect(result.status).toBe('ACCEPTED');
    });
});
```

#### Integration Tests

```typescript
describe('Full Game Flow', () => {
    it('should complete a full game cycle', async () => {
        // Start game
        const id = await startAdventure(account, 0, 'Hero');
        
        // Explore
        await explore(account, id, false);
        
        // Combat
        const beast = await getCurrentBeast(id);
        if (beast) {
            await attack(account, id, false);
        }
        
        // Check state
        const adventurer = await getAdventurer(id);
        expect(adventurer.experience).toBeGreaterThan(0);
    });
});
```

### Performance Optimization

#### Caching Strategy

```typescript
class GameCache {
    private cache = new Map();
    private ttl = 5000; // 5 seconds
    
    async get(key: string, fetcher: () => Promise<any>) {
        const cached = this.cache.get(key);
        
        if (cached && Date.now() - cached.timestamp < this.ttl) {
            return cached.data;
        }
        
        const data = await fetcher();
        this.cache.set(key, { data, timestamp: Date.now() });
        return data;
    }
}

const cache = new GameCache();

const getCachedAdventurer = (id: bigint) =>
    cache.get(`adventurer:${id}`, () => getAdventurer(id));
```

#### Batch Requests

```typescript
const batchGetAdventurers = async (ids: bigint[]) => {
    const promises = ids.map(id => getAdventurer(id));
    return await Promise.all(promises);
};
```

### Security Best Practices

#### Input Validation

```typescript
const validateAdventurerId = (id: any): bigint => {
    if (typeof id !== 'bigint' && typeof id !== 'string') {
        throw new Error('Invalid adventurer ID type');
    }
    
    const bigIntId = BigInt(id);
    
    if (bigIntId <= 0n) {
        throw new Error('Adventurer ID must be positive');
    }
    
    return bigIntId;
};
```

#### Rate Limiting

```typescript
class RateLimiter {
    private requests = new Map();
    private limit = 10; // requests per second
    
    canMakeRequest(key: string): boolean {
        const now = Date.now();
        const requests = this.requests.get(key) || [];
        
        // Remove old requests
        const recent = requests.filter(t => now - t < 1000);
        
        if (recent.length >= this.limit) {
            return false;
        }
        
        recent.push(now);
        this.requests.set(key, recent);
        return true;
    }
}
```

### Conclusion

This integration guide provides the foundation for building applications that interact with Loot Survivor. Whether you're creating a custom frontend, building tools, or extending the game, these patterns and examples will help you get started quickly and build robust integrations.


## Loot System

<div style={{ display: 'flex', gap: '2rem', alignItems: 'start', margin: '2rem 0', flexWrap: 'wrap' }}>
  <div
    style={{ 
fontSize: '1.1rem', 
lineHeight: '1.8', 
paddingRight: '2rem',
color: '#e5e5e5',
flex: '2',
minWidth: '300px'
}}
  >
    <p style={{ marginBottom: "1.2rem", fontWeight: "400" }}>
      The loot system in Loot Survivor is inspired by the original <a href="https://docs.loot.foundation/" style={{ color: "#3b82f6" }}>Loot collection</a> and forms the backbone of your adventurer's power progression.
    </p>

    <p style={{ marginBottom: "0", fontWeight: "400" }}>
      Understanding how items work, their tiers, and special properties is essential
      for survival in Death Mountain. Each piece of equipment can evolve and gain
      powerful bonuses as you progress through the dangerous depths.
    </p>
  </div>

  <div style={{ flex: '1', minWidth: '250px' }}>
    <img
      src="/docs/lootsurvivor/loot.png"
      alt="Loot Survivor Items Display"
      style={{
    width: "100%",
    display: "block",
    borderRadius: "8px",
    border: "2px solid #333",
  }}
    />

    <em
      style={{
    display: "block",
    textAlign: "center",
    marginTop: "0.5rem",
    fontSize: "0.9rem",
    opacity: "0.8",
  }}
    >
      Loot item display showing tier and special properties
    </em>
  </div>
</div>

### Item Properties

Each item has several key properties that determine its effectiveness:

* **Tier** - Base power level (T1-T5)
* **Greatness** - Special enhancement level (0-20)
* **Suffix** - Name suffix at Greatness 15+
* **Prefixes** - Additional bonuses at Greatness 19+
* **+1 Modifier** - +1 modifier at Greatness 20

### Item Tiers

Items in Loot Survivor are categorized into 5 tiers, with T1 being the most powerful:

| Tier   | Name      | Rarity    | Base Power    | Drop Rate | Description                                |
| ------ | --------- | --------- | ------------- | --------- | ------------------------------------------ |
| **T1** | Legendary | Highest   | 5× multiplier | \~0.066%  | Best-in-slot items with maximum base stats |
| **T2** | Epic      | Very High | 4× multiplier | \~0.2%    | Powerful items with excellent stats        |
| **T3** | Rare      | High      | 3× multiplier | \~0.4%    | Good equipment with solid performance      |
| **T4** | Uncommon  | Medium    | 2× multiplier | \~1.0%    | Decent upgrades over starting gear         |
| **T5** | Common    | Low       | 1× multiplier | \~1.65%   | Basic gear and starting equipment          |

**Tier Effects:**

* Higher tiers provide better base damage/protection
* Tier multiplier affects combat calculations
* Better tiers are more likely to have special properties
* All tiers can potentially have suffixes and prefixes

***

<div style={{ background: '#2a1a3e', padding: '1.5rem', borderRadius: '8px', border: '2px solid #a855f7', margin: '2rem 0', lineHeight: '1.8' }}>
  <div style={{ marginBottom: '1rem' }}>
    **🎮 Loot Survivor Implementation Note:**
  </div>

  <div style={{ marginBottom: '0' }}>
    Everything below this point represents **Loot Survivor's unique interpretation** of the original Loot collection. The Greatness System, combat types, materials, and their gameplay mechanics are specific to this game's implementation and not part of the base Loot specification.
  </div>
</div>

## Greatness System

Greatness is a special property that enhances items beyond their base tier:

### Greatness Levels

| Greatness | Enhancement     | Special Property           |
| --------- | --------------- | -------------------------- |
| **1-14**  | Base item       | Standard tier bonuses only |
| **15**    | Suffix unlocked | +3 stat bonus from suffix  |
| **16-18** | Enhanced suffix | Suffix bonuses continue    |
| **19**    | Prefix unlocked | Additional stat bonuses    |
| **20**    | Stat Bonus      | +1 assignable stat bonus   |

### How Greatness Works

* Items always start at greatness 1
* Greatness increases the item's overall power
* Greatness 15+ items gain [suffix bonuses](/lootsurvivor/loot/suffix-boost)
* Greatness 19+ items gain additional prefix [prefixes](/lootsurvivor/loot/prefixes)
* Greatness 20 items get a +1 stat modifier

***

## Equipment Types

Loot Survivor features 8 equipment slots for different item types:

| Equipment Slot | Item Types                            | Function |
| -------------- | ------------------------------------- | -------- |
| **Weapon**     | Katana, Wand, Club, Short Sword       | Weapon   |
| **Chest**      | Divine Robe, Shirt, Demon Husk        | Armor    |
| **Head**       | Crown, Cap, Helm                      | Armor    |
| **Waist**      | Ornate Belt, Sash, Heavy Belt         | Armor    |
| **Foot**       | Divine Slippers, Boots, Shoes         | Armor    |
| **Hand**       | Divine Gloves, Gloves, Gauntlets      | Armor    |
| **Neck**       | Amulet, Pendant, Necklace             | Jewelry  |
| **Ring**       | Platinum Ring, Gold Ring, Silver Ring | Jewelry  |

***

## Combat Types & Materials

Items have dual classifications that affect combat performance:

### Weapon Types

**⚔️ Blade Weapons**

* Strong vs Hide armor
* Weak vs Metal armor
* Examples: Katana, Short Sword, Scimitar

**🔨 Bludgeon Weapons**

* Strong vs Metal armor
* Weak vs Cloth armor
* Examples: Club, Mace, Warhammer

**✨ Magic Weapons**

* Strong vs Cloth armor
* Weak vs Hide armor
* Examples: Wand, Book, Ghost Wand

### Armor Materials

**🛡️ Hide Armor**

* Resists Blade attacks
* Weak to Magic attacks
* Examples: Leather armor, Dragon skin

**⚡ Metal Armor**

* Resists Bludgeon attacks
* Weak to Blade attacks
* Examples: Chain mail, Plate armor

**🧙 Cloth Armor**

* Resists Magic attacks
* Weak to Bludgeon attacks
* Examples: Robes, Shirts

***

## Item Acquisition

### Discovery Methods

Items can be obtained through several methods:

| Method                 | Rate                | Quality     | Notes                           |
| ---------------------- | ------------------- | ----------- | ------------------------------- |
| **Exploration**        | 3.3% of explores    | Random tier | Primary acquisition method      |
| **Market Purchase**    | Level-dependent     | Variable    | Costs gold, refresh on level up |
| **Starting Equipment** | 1 weapon guaranteed | T5 only     | Random weapon type              |

### Market System

* Market refreshes completely on each level up
* Available items are randomly generated
* Item count increases with adventurer level
* CHA stat reduces purchase prices
* Market items follow same tier distribution as drops

***

## Item Management

### Inventory System

* **8 Equipment Slots** - One for each equipment type
* **15 Bag Slots** - Additional storage for backup items
* **Auto-equip** - New items automatically equip if slots are empty
* **Gold Conversion** - Duplicate items convert to gold if no space

### Item Usage

**Equipping Items:**

* Drag from bag to equipment slot
* Items provide immediate stat bonuses
* Combat type/material affects battle performance
* Can switch equipment during exploration (not in combat)

**Item Stacking:**

* Only one item per equipment slot
* Identical items convert to gold
* Higher tier items typically replace lower tier
* Consider suffix/prefix bonuses when deciding

***

## Special Properties

### Suffixes

Items with Greatness 15+ gain powerful suffix bonuses. See [Suffix Boost Guide](/lootsurvivor/loot/suffix-boost) for complete details.

### Prefixes

Items with Greatness 19+ gain additional prefix bonuses that stack with suffix effects. These same prefixes are also used for named beasts in Beast Mode NFTs.

**Complete Prefix & Suffix Reference:** See [Prefixes Guide](/lootsurvivor/loot/prefixes) for the full library of all 69 prefixes and 18 suffixes.

***

## Summary

The loot system provides deep character customization through equipment choices, tier progression, and special properties. Understanding how tiers, greatness, suffixes, and prefixes work together allows you to build powerful adventurers capable of surviving Death Mountain's greatest challenges.

**Key Loot Principles:**

* Higher tiers provide better base power
* Greatness 15+ items gain significant suffix bonuses
* Greatness 19+ items gain additional prefix bonuses
* Combat type and material matter for battle effectiveness
* Market refreshes provide new acquisition opportunities each level


## Jewelry Items

Jewelry items increase the Adventurer's Luck, which is directly proportional to their critical hit chance.
20 Luck = 20% chance of a critical hit.
100 Luck = 100% chance of a critical hit.

The total Luck the Adventurer receives from their jewelry is equal to the total level of all their jewelry, both equipped and in their bag. For example, if you have a level 20 Bronze Ring in your bag and a level 20 Gold Ring equipped, your Luck will be 40.

It is possible to achieve 100 Luck and therefore a 100% critical hit chance with enough jewelry items.

Jewelry items also provide special abilities, but those only apply when they are equipped. Those special abilities are:

| Item          | Boost                                      |
| ------------- | ------------------------------------------ |
| Pendant       | 3% increase per level hide armor defence.  |
| Necklace      | 3% increase per level metal armor defence. |
| Amulet        | 3% increase per level cloth armor defence. |
| Bronze Ring   | No special ability (economy option).       |
| Silver Ring   | +1 bonus luck per level.                   |
| Gold Ring     | 3% per level in gold rewards from beasts.  |
| Platinum Ring | 3% per level in name match damage bonus.   |
| Titanium Ring | 3% per level in critical hit damage bonus. |


## Item & Beast Prefixes

Prefixes are special name modifiers that appear on high-greatness items (Level 19+) and named beasts. This comprehensive reference covers all 69 prefixes and 18 suffixes used throughout Loot Survivor.

### Prefix System Overview

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '2rem 0', lineHeight: '1.8' }}>
  <div style={{ marginBottom: '1rem' }}>
    **Dual Usage:** Prefixes serve two important functions in the game:
  </div>

  <div style={{ marginBottom: '1rem' }}>
    * **Item Enhancement**: High-greatness items (19+) gain prefix bonuses for additional stats
    * **Beast Names**: Named beasts (Level 19+) use these same prefixes for unique identities
    * **NFT Collection**: Beast Mode NFTs mint with prefix names for collectible variety
  </div>

  > **Cross-System Integration:** The same 69 prefixes create both powerful equipment and collectible named beasts!
</div>

### Complete Prefix Library (69 Total)

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.6' }}>
  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))', gap: '1.5rem', marginBottom: '1.5rem' }}>
    <div style={{ background: '#2a1a2a', padding: '1rem', borderRadius: '8px', border: '1px solid #dc2626' }}>
      #### 🌑 Dark Themes (17)

      1. Agony
      2. Apocalypse
      3. Armageddon
      4. Blight
      5. Blood
      6. Corruption
      7. Damnation
      8. Death
      9. Demon
      10. Dire
      11. Doom
      12. Dread
      13. Ghoul
      14. Gloom
      15. Grim
      16. Hate
      17. Horror
    </div>

    <div style={{ background: '#2a2a1a', padding: '1rem', borderRadius: '8px', border: '1px solid #eab308' }}>
      #### 🏆 Power & Creatures (17)

      18. Beast
      19. Behemoth
      20. Dragon
      21. Empyrean
      22. Fate
      23. Golem
      24. Honour
      25. Kraken
      26. Miracle
      27. Phoenix
      28. Skull
      29. Soul
      30. Spirit
      31. Victory
      32. Viper
      33. Brood
      34. Chimeric
    </div>

    <div style={{ background: '#1a2a2a', padding: '1rem', borderRadius: '8px', border: '1px solid #10b981' }}>
      #### 🌊 Elemental & Nature (17)

      35. Bramble
      36. Brimstone
      37. Carrion
      38. Corpse
      39. Dusk
      40. Eagle
      41. Gale
      42. Maelstrom
      43. Sol
      44. Storm
      45. Tempest
      46. Vortex
      47. Cataclysm
      48. Foe
      49. Havoc
      50. Onslaught
      51. Plague
    </div>

    <div style={{ background: '#2a1a3a', padding: '1rem', borderRadius: '8px', border: '1px solid #a855f7' }}>
      #### ✨ Mystical & Abstract (18)

      52. Glyph
      53. Hypnotic
      54. Loath
      55. Mind
      56. Morbid
      57. Oblivion
      58. Pain
      59. Pandemonium
      60. Rage
      61. Rapture
      62. Rune
      63. Sorrow
      64. Torment
      65. Vengeance
      66. Woe
      67. Wrath
      68. **Lights** ⭐
      69. **Shimmering** ⭐
    </div>
  </div>

  #### Ultra Rare Prefixes

  **Lights (#68)** and **Shimmering (#69)** are considered the most valuable and rare prefixes in the entire system, making items or beast NFTs with these names extremely sought after by collectors.
</div>

### Complete Suffix Library (18 Total)

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.6' }}>
  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', gap: '1rem' }}>
    <div>
      | ID | Suffix     |
      | -- | ---------- |
      | 1. | Bane       |
      | 2. | Root       |
      | 3. | Bite       |
      | 4. | Song       |
      | 5. | Roar       |
      | 6. | Grasp      |
      | 7. | Instrument |
      | 8. | Glow       |
      | 9. | Bender     |
    </div>

    <div>
      | ID  | Suffix  |
      | --- | ------- |
      | 10. | Shadow  |
      | 11. | Whisper |
      | 12. | Shout   |
      | 13. | Growl   |
      | 14. | Tear    |
      | 15. | Peak    |
      | 16. | Form    |
      | 17. | Sun     |
      | 18. | Moon    |
    </div>
  </div>

  **Suffix Usage:** Only applies to items with Greatness 15+ for stat bonuses. See [Suffix Boost Guide](/lootsurvivor/loot/suffix-boost) for detailed stat effects.
</div>

### Usage Examples

#### Item Naming Examples

<div style={{ background: '#1a2332', padding: '1.5rem', borderRadius: '8px', border: '1px solid #3b82f6', margin: '1rem 0', lineHeight: '1.8' }}>
  <div style={{ marginBottom: '1rem' }}>
    **High-Greatness Item Examples:**
  </div>

  <div style={{ marginBottom: '1rem' }}>
    * **"Doom Katana of Power"** - Prefix: Doom, Base: Katana, Suffix: of Power
    * **"Shimmering Divine Robe of Giants"** - Prefix: Shimmering, Base: Divine Robe, Suffix: of Giants
    * **"Blood Wand of Skill"** - Prefix: Blood, Base: Wand, Suffix: of Skill
  </div>

  **Beast Naming Examples:**

  <div style={{ marginBottom: '0' }}>
    * **"Apocalypse Dragon"** - Prefix: Apocalypse, Beast: Dragon
    * **"Lights Kraken"** - Prefix: Lights, Beast: Kraken
    * **"Storm Phoenix"** - Prefix: Storm, Beast: Phoenix
  </div>
</div>

### Cross-Reference Usage

#### When to Use This Page

<div style={{ background: '#0a0a0a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #333', margin: '1rem 0', lineHeight: '1.6' }}>
  **Reference Scenarios:**

  1. **Item Identification**: Understanding what prefix names mean on your equipment
  2. **Beast NFT Hunting**: Identifying valuable prefix combinations for collection
  3. **Market Evaluation**: Determining item value based on prefix rarity
  4. **Collection Planning**: Targeting specific prefixes for complete sets
  5. **Cross-Game Integration**: Understanding naming for Summit game access

  **Documentation Links:**

  * Items with prefixes: Reference this page from item evaluation
  * Named beasts: Reference this page from beast documentation
  * NFT collecting: Use for understanding collectible variety
</div>

### See Also

* [Loot System](/lootsurvivor/loot) - Main equipment and tier information
* [Suffix Boost Guide](/lootsurvivor/loot/suffix-boost) - Detailed suffix stat effects
* [Beast Collectibles](/lootsurvivor/beasts/collectibles) - Named beast NFT system
* [Beast Overview](/lootsurvivor/beasts) - Combat types and beast information


## Suffix Boosts

When an item reaches Greatness 15, it gains a powerful suffix that provides significant stat bonuses. These suffixes are based on the [16 Orders of Divinity](https://docs.loot.foundation/canonical-principles/loot/the-16-orders) from the original Loot collection and follow canonical loot lore.

> **⚡ Power Boost:** Suffix bonuses can make a T3 item with the right suffix more powerful than a base T1 item!

### How Suffixes Work

* **Greatness Requirement:** Items must reach Greatness 15 to unlock suffix bonuses
* **Random Assignment:** Suffixes are randomly assigned based on the Orders of Divinity
* **Permanent Bonuses:** Suffix bonuses are permanent and stack with base item stats
* **Lore Integration:** Each suffix follows canonical Loot Foundation principles

***

## Complete Suffix List

### Suffix Bonuses by Order

| Item Suffix          | Stat Bonuses                              | Total Bonus | Order Association                 |
| -------------------- | ----------------------------------------- | ----------- | --------------------------------- |
| **Of Power**         | Strength +3                               | +3          | Power-focused enhancement         |
| **Of Giant**         | Vitality +3                               | +3          | Health and endurance boost        |
| **Of Titans**        | Strength +2, Charisma +1                  | +3          | Balanced physical prowess         |
| **Of Skill**         | Dexterity +3                              | +3          | Agility and precision enhancement |
| **Of Perfection**    | Strength +1, Dexterity +1, Vitality +1    | +3          | Balanced all-around improvement   |
| **Of Brilliance**    | Intelligence +3                           | +3          | Mental acuity enhancement         |
| **Of Enlightenment** | Wisdom +3                                 | +3          | Spiritual awareness boost         |
| **Of Protection**    | Vitality +2, Dexterity +1                 | +3          | Defensive-focused bonuses         |
| **Of Anger**         | Strength +2, Dexterity +1                 | +3          | Aggressive combat enhancement     |
| **Of Rage**          | Wisdom +1, Strength +1, Charisma +1       | +3          | Controlled fury bonuses           |
| **Of Fury**          | Vitality +1, Charisma +1, Intelligence +1 | +3          | Passionate intensity boost        |
| **Of Vitriol**       | Intelligence +2, Wisdom +1                | +3          | Sharp mental enhancement          |
| **Of the Fox**       | Dexterity +2, Charisma +1                 | +3          | Cunning and agility boost         |
| **Of Detection**     | Wisdom +2, Dexterity +1                   | +3          | Awareness and reflexes            |
| **Of Reflection**    | Wisdom +2, Intelligence +1                | +3          | Contemplative wisdom boost        |
| **Of the Twins**     | Charisma +3                               | +3          | Social influence enhancement      |

***

## Suffix Categories

### Single Stat Focus

These suffixes provide maximum bonuses to one primary stat:

* **Of Power** - Pure Strength focus for maximum damage
* **Of Giant** - Pure Vitality focus for maximum health
* **Of Skill** - Pure Dexterity focus for escape mastery
* **Of Brilliance** - Pure Intelligence focus for obstacle avoidance
* **Of Enlightenment** - Pure Wisdom focus for ambush prevention
* **Of the Twins** - Pure Charisma focus for market optimization

### Balanced Combinations

These suffixes provide balanced stat distributions:

* **Of Perfection** - Equal bonuses across STR/DEX/VIT
* **Of Rage** - Equal bonuses across WIS/STR/CHA
* **Of Fury** - Equal bonuses across VIT/CHA/INT

### Specialized Builds

These suffixes target specific build archetypes:

* **Of Titans** - Combat-focused (STR+CHA)
* **Of Protection** - Defense-focused (VIT+DEX)
* **Of Anger** - Aggressive melee (STR+DEX)
* **Of Vitriol** - Mental mastery (INT+WIS)
* **Of the Fox** - Agile trader (DEX+CHA)
* **Of Detection** - Alert explorer (WIS+DEX)
* **Of Reflection** - Wise scholar (WIS+INT)

***

## Suffix Strategy

### Evaluating Suffix Value

When comparing items with suffixes, consider:

1. **Your Build Focus** - Does the suffix support your stat priorities?
2. **Current Weaknesses** - Does the suffix shore up weak areas?
3. **Base Tier vs Suffix** - A T3+suffix might beat a base T1
4. **Total Stat Impact** - All +3 bonuses are equally valuable mathematically

### Suffix Synergies

**Combat Builds:**

* **Of Power** - Maximum damage output
* **Of Titans** - Damage + market efficiency
* **Of Anger** - Damage + escape capability

**Survival Builds:**

* **Of Giant** - Maximum health pool
* **Of Protection** - Health + escape ability
* **Of Perfection** - Balanced survivability

**Utility Builds:**

* **Of the Fox** - Escape + market efficiency
* **Of Detection** - Awareness + agility
* **Of Reflection** - Mental mastery

***

## Summary

Suffix bonuses transform the loot system from simple tier progression to complex item evaluation. A well-rolled suffix can make any item tier competitive, while the wrong suffix might make you overlook a potentially powerful piece of equipment.

**Key Suffix Principles:**

* All suffixes provide exactly +3 total stat points
* Suffixes unlock at Greatness 15
* Suffix distribution matters more than individual bonuses
* Consider your build when evaluating suffix value
* Don't automatically dismiss lower tiers with good suffixes


## Combat Guide

Combat in Loot Survivor is a turn-based system where preparation meets execution. Every encounter tests your understanding of type advantages, stat optimization, and tactical decision-making. Master the art of battle to survive Death Mountain's deadliest challenges.

> **🎯 Combat Philosophy:** Turn-based combat means every action counts. Sometimes survival means avoiding the fight entirely.

### Battle Interface

<div style={{ maxWidth: "900px", margin: "2rem auto" }}>
  <img
    src="/docs/lootsurvivor/battle.png"
    alt="Loot Survivor Battle Screen"
    style={{
    width: "100%",
    display: "block",
    margin: "0 auto",
    borderRadius: "8px",
    border: "2px solid #333",
  }}
  />

  <br />

  <em style={{ display: "block", textAlign: "center" }}>
    Figure: Battle interface showing adventurer vs beast encounter
  </em>
</div>

***

## Combat Mechanics

### Turn-Based Combat Flow

<div
  style={{
backgroundColor: "rgba(16, 185, 129, 0.1)",
border: "2px solid #10b981",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#10b981" }}>⏱️ Combat Turn Order</h3>

  <p style={{ marginBottom: "1rem" }}>
    Combat follows a strict turn-based sequence where <strong>adventurers always act first</strong>:
  </p>

  <ol style={{ marginBottom: 0 }}>
    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Adventurer Turn</strong> - Choose your action:

      <ul style={{ marginTop: "0.5rem", marginLeft: "1rem" }}>
        <li>⚔️ Attack the beast</li>
        <li>🏃 Attempt to flee</li>
        <li>🔄 Switch equipment (beast gets free attack)</li>
      </ul>
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Beast Counterattack</strong> - If not defeated or fled:

      <ul style={{ marginTop: "0.5rem", marginLeft: "1rem" }}>
        <li>Beast automatically attacks back</li>
        <li>Targets a <strong>random armor slot</strong> (1 of 5: Head, Chest, Waist, Foot, Hand)</li>
        <li>Damage reduced by armor in that specific slot</li>
      </ul>
    </li>

    <li>
      <strong>Repeat</strong> - Combat continues until victory, defeat, or successful escape
    </li>
  </ol>
</div>

> **💡 Key Insight:** Since beasts attack random armor slots, having balanced armor coverage is more important than stacking defense in one slot!

### Damage System

<div
  style={{
backgroundColor: "rgba(251, 191, 36, 0.1)",
border: "2px solid #fbbf24",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#fbbf24" }}>⚡ Understanding Power</h3>

  <p style={{ marginBottom: "0.75rem" }}>
    <strong>Power</strong> is displayed in combat for the base damage before modifiers.
    It appears as a number on item and beast info showing the raw damage potential.
  </p>

  <p style={{ fontFamily: "monospace", fontSize: "1.1rem", marginBottom: 0 }}>
    <strong>Power = Weapon Level × (6 - Weapon Tier)</strong>
  </p>
</div>

#### Combat Damage Modifiers

The full damage amount includes several factors during combat:

* **⚔️ Base Damage** - Your Power value (Weapon tier × level formula above)
* **🎯 Type Advantage** - +50% when strong, -50% when weak
* **💪 Strength Bonus** - +10% damage per STR point
* **✨ Critical Hits** - LUCK/100% chance for 100% bonus damage (see [Combat Mechanics](/lootsurvivor/combat) for details)

### Type Advantage System

<div
  style={{
display: "flex",
justifyContent: "center",
marginBottom: "2rem",
marginTop: "2rem"
}}
>
  <div
    style={{
  position: "relative",
  width: "350px",
  height: "300px"
}}
  >
    {/* Brute - Top */}

    <div
      style={{
    position: "absolute",
    top: "0",
    left: "50%",
    transform: "translateX(-50%)",
    textAlign: "center",
    backgroundColor: "#dc2626",
    padding: "1rem 1.5rem",
    borderRadius: "12px",
    border: "3px solid #991b1b",
    minWidth: "140px",
    boxShadow: "0 4px 12px rgba(220, 38, 38, 0.3)"
  }}
    >
      <div style={{ fontSize: "2rem", marginBottom: "0.25rem" }}>🔨</div>
      <div style={{ fontWeight: "bold", color: "#fff", fontSize: "1.1rem" }}>Brute</div>
      <div style={{ fontSize: "0.75rem", color: "#fca5a5", marginTop: "0.25rem" }}>Bludgeon + Metal</div>
    </div>

    {/* Hunter - Bottom Left */}

    <div
      style={{
    position: "absolute",
    bottom: "0",
    left: "0",
    textAlign: "center",
    backgroundColor: "#059669",
    padding: "1rem 1.5rem",
    borderRadius: "12px",
    border: "3px solid #047857",
    minWidth: "140px",
    boxShadow: "0 4px 12px rgba(5, 150, 105, 0.3)"
  }}
    >
      <div style={{ fontSize: "2rem", marginBottom: "0.25rem" }}>⚔️</div>
      <div style={{ fontWeight: "bold", color: "#fff", fontSize: "1.1rem" }}>Hunter</div>
      <div style={{ fontSize: "0.75rem", color: "#86efac", marginTop: "0.25rem" }}>Blade + Hide</div>
    </div>

    {/* Magical - Bottom Right */}

    <div
      style={{
    position: "absolute",
    bottom: "0",
    right: "0",
    textAlign: "center",
    backgroundColor: "#7c3aed",
    padding: "1rem 1.5rem",
    borderRadius: "12px",
    border: "3px solid #6d28d9",
    minWidth: "140px",
    boxShadow: "0 4px 12px rgba(124, 58, 237, 0.3)"
  }}
    >
      <div style={{ fontSize: "2rem", marginBottom: "0.25rem" }}>✨</div>
      <div style={{ fontWeight: "bold", color: "#fff", fontSize: "1.1rem" }}>Magical</div>
      <div style={{ fontSize: "0.75rem", color: "#ddd6fe", marginTop: "0.25rem" }}>Magic + Cloth</div>
    </div>

    {/* Center circular arrows */}

    <svg
      style={{
    position: "absolute",
    top: "50%",
    left: "50%",
    transform: "translate(-50%, -50%)",
    width: "100px",
    height: "100px",
    pointerEvents: "none"
  }}
    >
      {/* Three arrows showing advantage flow */}

      {/* Brute to Hunter (pointing bottom left) */}

      <path d="M 50 15 L 15 75" stroke="white" strokeWidth="3" markerEnd="url(#arrowhead)" opacity="0.9" />

      {/* Hunter to Magical (pointing right) */}

      <path d="M 15 75 L 85 75" stroke="white" strokeWidth="3" markerEnd="url(#arrowhead)" opacity="0.9" />

      {/* Magical to Brute (pointing top left) */}

      <path d="M 85 75 L 50 15" stroke="white" strokeWidth="3" markerEnd="url(#arrowhead)" opacity="0.9" />

      <defs>
        <marker id="arrowhead" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
          <polygon points="0 0, 8 3, 0 6" fill="white" />
        </marker>
      </defs>
    </svg>
  </div>
</div>

<div
  style={{
textAlign: "center",
marginBottom: "1rem",
fontSize: "0.95rem",
color: "#999"
}}
>
  <span style={{ color: "#fca5a5" }}>Bludgeon + Metal</span> beats
  <span style={{ color: "#86efac" }}> Blade + Hide</span> beats
  <span style={{ color: "#ddd6fe" }}> Magic + Cloth</span> beats
  <span style={{ color: "#fca5a5" }}> Bludgeon + Metal</span>
</div>

#### Type Advantage Effects

**📈 With Advantage:**

* **Damage Multiplier:** +50%
* **Example:** 20 base damage → 30 damage output
* **Visual Cue:** Green damage numbers in combat log

**📉 With Disadvantage:**

* **Damage Multiplier:** -50%
* **Example:** 20 base damage → 10 damage output
* **Visual Cue:** Red damage numbers in combat log

#### Strategic Equipment Sets

<div
  style={{ 
background: 'linear-gradient(135deg, rgba(147, 51, 234, 0.1) 0%, rgba(59, 130, 246, 0.1) 100%)',
border: '2px solid #6366f1',
borderRadius: '12px',
padding: '1.5rem',
marginTop: '1.5rem'
}}
>
  <div style={{ marginBottom: '1rem' }}>
    <strong style={{ color: '#a78bfa', fontSize: '1.1rem' }}>🛡️ Full Armor Sets</strong>

    <p style={{ marginTop: '0.5rem', marginBottom: 0, lineHeight: '1.6' }}>
      Each armor type excels against specific attacks: <strong>Metal</strong> resists Blade, <strong>Hide</strong> resists Magic,
      <strong>Cloth</strong> resists Bludgeon. But beware - each has a weakness!
    </p>
  </div>

  <div style={{ marginBottom: '1rem' }}>
    <strong style={{ color: '#f59e0b', fontSize: '1.1rem' }}>⚔️ Offensive Priority</strong>

    <p style={{ marginTop: '0.5rem', marginBottom: 0, lineHeight: '1.6' }}>
      Your weapon choice matters more than armor. Remember: <strong>Bludgeon</strong> crushes Hide,
      <strong>Blade</strong> slices Cloth, <strong>Magic</strong> pierces Metal. +50% damage is huge!
    </p>
  </div>

  <div style={{ marginBottom: '1rem' }}>
    <strong style={{ color: '#10b981', fontSize: '1.1rem' }}>🎯 Beast Hunting</strong>

    <p style={{ marginTop: '0.5rem', marginBottom: 0, lineHeight: '1.6' }}>
      When hunting specific beasts, matching your full armor set to counter their attacks is powerful.
      Know your target and gear up accordingly for maximum survivability.
    </p>
  </div>

  <div
    style={{ 
background: 'rgba(255, 255, 255, 0.05)',
borderRadius: '8px',
padding: '1rem',
marginTop: '1rem'
}}
  >
    <strong>💡 Pro Strategy:</strong> Early game, prioritize covering all armor slots with appropriate types over hunting for higher tiers!
  </div>
</div>

***

## Combat Actions

### ⚔️ Attack Options

#### Single Attack

Execute one calculated strike against your opponent.

**Stat Influences:**

* **STR:** +10% damage per point
* **LUCK:** Critical hit chance (LUCK/100%)
* **Weapon Tier:** Base damage multiplier

**Best for:** Controlled combat, testing damage, conserving resources

#### Attack Until Death

Chain attacks automatically until victory or defeat.

**⚠️ High Risk Mode:**

* No control once initiated
* Fight continues until resolution
* Cannot flee mid-sequence

**Use when:**

* Beast health is very low
* You have type advantage
* Confident in victory
* Emergency/desperate situations

### 🏃 Flee Mechanics

**Flee Formula:**

```
Success Rate = (DEX / Level) × 100%
```

| DEX/Level | Success | Level 10 Example | Level 20 Example |
| --------- | ------- | ---------------- | ---------------- |
| 0.5       | 50%     | DEX 5            | DEX 10           |
| 0.75      | 75%     | DEX 7-8          | DEX 15           |
| 1.0       | 100%    | DEX 10           | DEX 20           |
| 1.5       | 100%    | DEX 15           | DEX 30           |

**Key Points:**

* DEX equal to level = 100% success
* Success rate caps at 100%
* Failed flee attempts waste a turn
* Ambush encounters have no additional penalties

### 🛡️ Equipment Switching

You can change your equipment mid-combat to gain type advantages, but the beast gets a free attack when you do. Strategic swapping can turn a losing fight into victory - switch to counter their type for +50% damage or -50% damage reduction.

> **💡 Important:** Bundle all gear changes into one action to minimize the number of free attacks the beast gets. Multiple switches still only give the beast one free attack!

***

## Combat Decision Making

When entering combat, consider these factors:

* **🏃 Flee** - When you have low HP, type disadvantage, or facing a stronger beast
* **🔄 Switch Gear** - When you have the wrong equipment type and need advantage
* **⚔️ Attack** - When you have good matchup and are confident in victory
* **💀 All-Out Attack** - When beast has very low HP and victory is guaranteed

***

## Combat Rewards

### Experience Points (XP)

<div
  style={{
backgroundColor: "rgba(34, 197, 94, 0.1)",
border: "2px solid #22c55e",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#22c55e" }}>💰 Victory Rewards</h3>

  <p style={{ marginBottom: "1rem" }}>
    Defeating beasts grants XP and gold based on their power, with bonuses for finding items:
  </p>

  <div style={{ marginBottom: "1rem" }}>
    <strong>Base Reward Formulas:</strong>

    <div style={{ fontFamily: "monospace", marginLeft: "1rem", marginTop: "0.5rem" }}>
      Adventurer XP = Beast Power / 2<br />
      Item XP = 2 \* Adventurer XP<br />
      Gold = Beast Power / 2 (same as XP)
    </div>
  </div>

  <div>
    <strong>Level Decay:</strong>

    <p style={{ marginLeft: "1rem", marginTop: "0.5rem", marginBottom: 0 }}>
      XP rewards decrease as you level up (2% per level, max 95% reduction)<br />
      <span style={{ color: "#fbbf24" }}>Gold rewards do NOT decay - always full value!</span>
    </p>
  </div>
</div>

#### Reward Calculation Examples

| Your Level | Beast (T3, Lv10) | Base Rewards | XP After Decay | Gold (No Decay) | Item XP |
| ---------- | ---------------- | ------------ | -------------- | --------------- | ------- |
| Level 1    | Power: 30        | 15           | 15 XP (0%)     | 15 🪙           | 30 XP   |
| Level 10   | Power: 30        | 15           | 12 XP (-20%)   | 15 🪙           | 24 XP   |
| Level 25   | Power: 30        | 15           | 7 XP (-50%)    | 15 🪙           | 15 XP   |
| Level 50+  | Power: 30        | 15           | 1 XP (-95%)    | 15 🪙           | 2 XP    |

> **💡 Tip:** The XP decay encourages fighting appropriate challenges, but gold rewards stay consistent - making every victory valuable!

***

## Summary

Combat success in Loot Survivor comes from understanding type advantages, optimizing your stats, and making tactical decisions. Every battle offers multiple approaches - from switching gear for advantages to knowing when discretion is the better part of valor.

**Key Combat Principles:**

* Type advantage provides significant damage bonuses/penalties
* STR scaling makes strength investment worthwhile for damage dealers
* DEX equal to your level guarantees successful escapes
* Gear switching can turn losing fights into victories
* Sometimes the best fight is the one you avoid


## Exploration Guide

Exploration is the heart of Loot Survivor's gameplay loop. Every step into the unknown brings potential rewards and deadly dangers. Understanding the exploration system is key to surviving Death Mountain's treacherous depths.

> **🎲 Random Encounters:** Every exploration is a roll of the dice with equal chances for discovery, obstacles, or beasts!

### Exploration Interface

<div style={{ maxWidth: "900px", margin: "2rem auto" }}>
  <img
    src="/docs/lootsurvivor/explore.png"
    alt="Loot Survivor Exploration Screen"
    style={{
    width: "100%",
    display: "block",
    margin: "0 auto",
    borderRadius: "8px",
    border: "2px solid #333",
  }}
  />

  <br />

  <em style={{ display: "block", textAlign: "center" }}>
    Figure: Exploration interface with adventure log and market
  </em>
</div>

***

## How Exploration Works

When you click "Explore", the game rolls for one of three equally likely outcomes:

* **📦 Item Discovery (33.33%)** - Find gold, potions, or equipment
* **🪨 Obstacle (33.33%)** - Environmental hazards to overcome
* **👹 Beast Encounter (33.33%)** - Mandatory combat encounters

### Item Discovery Breakdown

When you hit the 33% item discovery chance, it subdivides into:

* **💰 Gold (45% of discoveries)** - Currency for market purchases (\~15% of all explores)
* **🧪 Health Potion (45% of discoveries)** - Restores HP when used (\~15% of all explores)
* **⚔️ Equipment (10% of discoveries)** - Weapons, armor, jewelry (\~3.3% of all explores)

***

## Discovery Types

### 💰 Gold Discovery

**Formula:** `Gold = Random(1 to Adventurer Level)`

| Level | Gold Range | Average |
| ----- | ---------- | ------- |
| 5     | 1-5g       | 3g      |
| 10    | 1-10g      | 5.5g    |
| 20    | 1-20g      | 10.5g   |
| 30    | 1-30g      | 15.5g   |
| 50    | 1-50g      | 25.5g   |

**Key Features:**

* Amount scales with your level
* Can be saved between explorations
* CHA stat reduces market prices
* Essential for equipment upgrades
* **Maximum capacity: 511 gold**

> **💰 Gold Cap:** You can only carry up to 511 gold. Any excess is lost, so spend wisely!

### ⚔️ Equipment Discovery

Equipment drops are your primary source of gear upgrades. When you discover loot (3.3% of all explores), the tier distribution is:

| Item Tier          | Drop Rate | Of All Explores | Description     |
| ------------------ | --------- | --------------- | --------------- |
| **T5 (Common)**    | 50%       | \~1.65%         | Basic gear      |
| **T4 (Uncommon)**  | 30%       | \~1.0%          | Decent upgrades |
| **T3 (Rare)**      | 12%       | \~0.4%          | Good equipment  |
| **T2 (Epic)**      | 6%        | \~0.2%          | Powerful items  |
| **T1 (Legendary)** | 2%        | \~0.066%        | Best in slot    |

> **Item assigning:** Items are automatically equipped or added to bag if there are free slots. Otherwise, if items are already discovered or there is no space they are converted to gold.

### 🧪 Health Discovery

**Formula:** `HP = Random(2 to Level × 2)`

| Level | HP Range | Average | % of Max HP |
| ----- | -------- | ------- | ----------- |
| 5     | 2-10 HP  | 6 HP    | \~0.6%      |
| 10    | 2-20 HP  | 11 HP   | \~1.1%      |
| 20    | 2-40 HP  | 21 HP   | \~2.1%      |
| 30    | 2-60 HP  | 31 HP   | \~3.0%      |
| 50    | 2-100 HP | 51 HP   | \~5.0%      |

**Potion Information:**

* Found in 15% of all explores
* Instantly restores HP when discovered
* **Maximum health: 1023 HP** (adventurer cap)

> **❤️ Health Cap:** Adventurers have a maximum health of 1023 HP. Health potions cannot exceed this limit.

### ⭐ Experience Gains

Exploration provides consistent experience points for leveling up:

| XP Source          | XP Gained                           | Scaling | Risk Level |
| ------------------ | ----------------------------------- | ------- | ---------- |
| **Item Discovery** | 1                                   | None    | Safe       |
| **Beast Kills**    | Beast Level × (Tier Multiplier - 1) | Decayed | High       |
| **Obstacles**      | Same as above                       | Decayed | Medium     |

***

## Beast Encounters

<div style={{ background: '#2a1a2a', padding: '1.5rem', borderRadius: '8px', border: '2px solid #dc2626', margin: '2rem 0' }}>
  ### ⚠️ Mandatory Combat

  **IMPORTANT:** Discovering a beast during exploration **always locks you into combat**. There is no way to avoid the fight once a beast is encountered.

  **Combat is Unavoidable:**

  * Beast encounters force immediate battle
  * No option to flee before combat begins
  * You must fight until victory, defeat, or successful flee attempt
  * See the [Battle Guide](/lootsurvivor/guide/battle) for detailed combat mechanics
</div>

### Beast Strength Calculation

When a beast is discovered, its level and health are determined by your adventurer level:

#### Beast Level Formula

```
Base Level = 1 + Random(0 to Adventurer Level × 3 - 1)
Final Level = Base Level + Difficulty Bonus
```

**Difficulty Bonuses by Adventurer Level:**

| Adventurer Level | Difficulty Bonus | Level Range | Average Level |
| ---------------- | ---------------- | ----------- | ------------- |
| **1-19**         | +0               | 1-57        | \~29          |
| **20-29**        | +10              | 11-97       | \~54          |
| **30-39**        | +20              | 21-137      | \~79          |
| **40-49**        | +40              | 41-187      | \~114         |
| **50+**          | +80              | 81-230+     | \~155+        |

#### Beast Health Formula

```
Base Health = 1 + Random(0 to Adventurer Level × 20 - 1)
Final Health = Base Health + Health Bonus
```

**Health Bonuses by Adventurer Level:**

| Adventurer Level | Health Bonus | Health Range | Average Health |
| ---------------- | ------------ | ------------ | -------------- |
| **1-19**         | +10          | 11-390       | \~200          |
| **20-29**        | +100         | 101-680      | \~390          |
| **30-39**        | +200         | 201-980      | \~590          |
| **40-49**        | +400         | 401-1023\*   | \~712          |
| **50+**          | +500         | 501-1023\*   | \~762          |

\*Capped at maximum health of 1023 HP

> **⚠️ Power Spikes:** Beasts get significantly stronger at levels 20, 30, 40, and 50. Plan your upgrades accordingly!
>
> **❤️ Beast Health Cap:** Like adventurers, beasts have a maximum health of 1023 HP.

### Ambush Disadvantages

Beast encounters during exploration catch you off-guard with several penalties:

* **⚡ Initiative Loss** - Beast attacks first in combat
* **🛡️ No Preparation** - Cannot switch gear before combat begins

### Ambush Avoidance

**Ambush Avoidance Formula:**

```
Avoidance Chance = (WIS / Level) × 100%
```

| WIS/Level | Avoidance | Level 10 Example | Level 20 Example |
| --------- | --------- | ---------------- | ---------------- |
| 0.5       | 50%       | WIS 5            | WIS 10           |
| 0.75      | 75%       | WIS 7-8          | WIS 15           |
| 1.0       | 100%      | WIS 10           | WIS 20           |
| 1.5       | 100%      | WIS 15           | WIS 30           |

**Key Points:**

* WIS equal to level = 100% avoidance
* Success rate caps at 100%
* Only applies to beast encounters
* Does not prevent the encounter entirely

> **👁️ Important:** Wisdom helps avoid the ambush penalties, but you will still be locked into combat when a beast is encountered.

***

## Environmental Challenges

### 🪨 Obstacle System

Obstacles are unavoidable environmental hazards with three distinct categories:

#### Obstacle Types

**✨ Magical Obstacles (25 types)**

* Examples: Demonic Altar, Vortex of Despair, Cursed Tomb
* **Counter:** Hide armor

**🗡️ Blade Obstacles (25 types)**

* Examples: Pendulum Blades, Poison Darts, Hidden Arrows
* **Counter:** Metal armor

**🔨 Bludgeon Obstacles (25 types)**

* Examples: Collapsing Ceiling, Rolling Boulder, Crushing Walls
* **Counter:** Cloth armor

#### Obstacle Level Calculation

When an obstacle is encountered, its level is determined using the same formula as beast levels:

```
Base Level = 1 + Random(0 to Adventurer Level × 3 - 1)
Final Level = Base Level + Difficulty Bonus
```

**Difficulty Bonuses by Adventurer Level:**

| Adventurer Level | Difficulty Bonus | Obstacle Level Range | Average Level |
| ---------------- | ---------------- | -------------------- | ------------- |
| **1-19**         | +0               | 1-57                 | \~29          |
| **20-29**        | +10              | 11-97                | \~54          |
| **30-39**        | +20              | 21-137               | \~79          |
| **40-49**        | +40              | 41-187               | \~114         |
| **50+**          | +80              | 81-230+              | \~155+        |

> **📊 Note:** Unlike beasts, obstacles don't have health - they deal damage based on their level if not avoided.

#### Damage Mitigation

| Method            | Effect               | Requirement          |
| ----------------- | -------------------- | -------------------- |
| **Intelligence**  | Complete avoidance   | INT ≥ obstacle level |
| **Armor Match**   | 50% damage reduction | Correct armor type   |
| **No Protection** | Full damage          | No mitigation        |

***

## Summary

Exploration provides the foundation for your Death Mountain adventure through consistent rewards and progression opportunities. Understanding the 33/33/33 split between discoveries, obstacles, and beasts helps you make informed decisions about when and how to explore.

**Key Takeaways:**

* Equal chances for all three outcome types
* Higher levels = better gold and health discoveries
* LUCK influences equipment tier drops
* INT helps avoid obstacles, WIS helps avoid ambushes
* Choose exploration modes based on your current needs


## Getting Started with Loot Survivor

Welcome, adventurer! This guide will help you begin your journey into the depths of Death Mountain. Whether you're new to blockchain gaming or Starknet, we'll get you up and running quickly.

> **⚡ Fast Track:** Want to play right now? Click "Practice Mode" and start exploring immediately!

### Game Modes

<div
  style={{
  display: "flex",
  gap: "1.5rem",
  marginTop: "2rem",
  marginBottom: "2rem",
  flexWrap: "wrap",
  maxWidth: "800px",
}}
>
  <div
    style={{
    flex: "1",
    minWidth: "280px",
    backgroundColor: "rgba(26, 26, 26, 0.8)",
    border: "2px solid #444",
    borderRadius: "12px",
    padding: "2rem",
    boxShadow: "0 4px 12px rgba(0, 0, 0, 0.3)",
    transition: "all 0.3s ease",
    ":hover": {
      borderColor: "#666",
      transform: "translateY(-2px)",
      boxShadow: "0 6px 16px rgba(0, 0, 0, 0.4)",
    },
  }}
  >
    <h3
      style={{
      marginTop: 0,
      marginBottom: "1.25rem",
      fontSize: "1.25rem",
      fontWeight: "600",
      color: "#fff",
    }}
    >
      🎮 Practice Mode
    </h3>

    <ul
      style={{
      listStyleType: "none",
      paddingLeft: 0,
      margin: 0,
      fontSize: "0.95rem",
      lineHeight: "1.6",
    }}
    >
      <li style={{ marginBottom: "0.75rem", color: "#4ade80" }}>
        ✓ Instant play
      </li>

      <li style={{ marginBottom: "0.75rem", color: "#4ade80" }}>
        ✓ No rewards or progression
      </li>

      <li style={{ color: "#4ade80" }}>✓ No wallet needed</li>
    </ul>

    <div
      style={{
      marginTop: "1.5rem",
      paddingTop: "1.5rem",
      borderTop: "1px solid #444",
      fontSize: "0.85rem",
      color: "#999",
      textAlign: "center",
    }}
    >
      Perfect for learning
    </div>
  </div>

  <div
    style={{
    flex: "1",
    minWidth: "280px",
    backgroundColor: "rgba(26, 26, 26, 0.8)",
    border: "2px solid #444",
    borderRadius: "12px",
    padding: "2rem",
    boxShadow: "0 4px 12px rgba(0, 0, 0, 0.3)",
    transition: "all 0.3s ease",
    position: "relative",
    overflow: "hidden",
  }}
  >
    <div
      style={{
      position: "absolute",
      top: "-50px",
      right: "-50px",
      width: "100px",
      height: "100px",
      backgroundColor: "rgba(251, 191, 36, 0.1)",
      borderRadius: "50%",
      filter: "blur(40px)",
    }}
    />

    <h3
      style={{
      marginTop: 0,
      marginBottom: "1.25rem",
      fontSize: "1.25rem",
      fontWeight: "600",
      color: "#fff",
    }}
    >
      🏆 Beast Mode
    </h3>

    <ul
      style={{
      listStyleType: "none",
      paddingLeft: 0,
      margin: 0,
      fontSize: "0.95rem",
      lineHeight: "1.6",
    }}
    >
      <li style={{ marginBottom: "0.75rem", color: "#fbbf24" }}>
        ✓ Dungeon Ticket entry
      </li>

      <li style={{ marginBottom: "0.75rem", color: "#fbbf24" }}>
        ✓ Collectible beasts
      </li>

      <li style={{ color: "#fbbf24" }}>✓ Requires wallet setup</li>
    </ul>

    <div
      style={{
      marginTop: "1.5rem",
      paddingTop: "1.5rem",
      borderTop: "1px solid #444",
      fontSize: "0.85rem",
      color: "#999",
      textAlign: "center",
    }}
    >
      Full blockchain experience
    </div>
  </div>
</div>

> **Recommendation:** Start with Practice Mode to learn the basics, then upgrade to Beast Mode for the full experience.

### Play Anywhere

<div
  style={{
  backgroundColor: "rgba(34, 197, 94, 0.1)",
  border: "2px solid #22c55e",
  borderRadius: "8px",
  padding: "1.5rem",
  marginTop: "2rem",
  marginBottom: "2rem",
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#22c55e" }}>
    📱 Fully Mobile Ready
  </h3>

  <p style={{ marginBottom: "1.5rem", fontSize: "1.1rem", lineHeight: "1.6" }}>
    Loot Survivor is designed for seamless gameplay across all devices. Whether
    you prefer the immersive desktop experience or the convenience of mobile
    gaming, enjoy the same full-featured adventure anywhere you go.
  </p>

  <div
    style={{
    display: "grid",
    gridTemplateColumns: "1fr 1fr",
    gap: "1.5rem",
    marginBottom: "1.5rem",
  }}
  >
    <div
      style={{
      textAlign: "center",
      padding: "1rem",
      backgroundColor: "rgba(255, 255, 255, 0.05)",
      borderRadius: "8px",
      border: "1px solid rgba(34, 197, 94, 0.3)",
    }}
    >
      <div style={{ fontSize: "2rem", marginBottom: "0.5rem" }}>🖥️</div>
      <h4 style={{ margin: "0 0 0.5rem 0", color: "#22c55e" }}>Desktop</h4>

      <p style={{ margin: "0 0 0.75rem 0", fontSize: "0.9rem", opacity: "0.9" }}>
        AI-powered immersive visuals with detailed UI
      </p>

      <div style={{ fontSize: "0.8rem", opacity: "0.7", lineHeight: "1.4" }}>
        Latest AI technology creates stunning visual experiences for deep
        exploration sessions
      </div>
    </div>

    <div
      style={{
      textAlign: "center",
      padding: "1rem",
      backgroundColor: "rgba(255, 255, 255, 0.05)",
      borderRadius: "8px",
      border: "1px solid rgba(34, 197, 94, 0.3)",
    }}
    >
      <div style={{ fontSize: "2rem", marginBottom: "0.5rem" }}>📱</div>
      <h4 style={{ margin: "0 0 0.5rem 0", color: "#22c55e" }}>Mobile</h4>

      <p style={{ margin: "0 0 0.75rem 0", fontSize: "0.9rem", opacity: "0.9" }}>
        Pixel-art adventurer for fast-paced gameplay
      </p>

      <div style={{ fontSize: "0.8rem", opacity: "0.7", lineHeight: "1.4" }}>
        Classic pixel aesthetics optimized for quick sessions and touch controls
      </div>
    </div>
  </div>

  <div style={{ textAlign: "center" }}>
    <a
      href="/lootsurvivor/platforms"
      style={{
      color: "#22c55e",
      textDecoration: "none",
      fontWeight: "600",
      fontSize: "1rem",
    }}
    >
      📸 View Platform Comparison & Screenshots →
    </a>
  </div>
</div>

### Main Menu Interface

<div style={{ maxWidth: "900px", margin: "2rem auto" }}>
  <img
    src="/docs/lootsurvivor/menu.png"
    alt="Loot Survivor Main Menu"
    style={{
    width: "100%",
    display: "block",
    margin: "0 auto",
    borderRadius: "8px",
    border: "2px solid #333",
  }}
  />

  <br />

  <em style={{ display: "block", textAlign: "center" }}>
    Figure: Main menu interface
  </em>
</div>

***

## Beast Mode Setup

> **Ready for the full experience?** Beast Mode offers real blockchain rewards, NFT beasts, and permanent progression.

### Prerequisites

**🔐 Wallet Required**

* Cartridge Controller
* Built for gaming with gasless transactions
* Supports social login and multi-platform access

**💰 Payment Options**

* Multiple crypto tokens accepted (ETH, USDC, STRK, and more)
* Credit card payments supported
* Variable ticket pricing based on demand

### Wallet Setup Process

#### Step 1: Create Controller Wallet

<div
  style={{
  display: "flex",
  gap: "2rem",
  alignItems: "flex-start",
  margin: "1rem 0",
  flexWrap: "wrap",
}}
>
  <div style={{ flex: "1", minWidth: "300px" }}>
    <strong>Choose your signup method:</strong>

    <ul
      style={{
      paddingLeft: "1.5rem",
      marginTop: "0.5rem",
      listStyleType: "disc",
    }}
    >
      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        <strong>🔐 Social Login</strong> - Discord, Google, GitHub
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        <strong>🔑 Passkey</strong> - Biometric authentication
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        <strong>💼 Existing Wallet</strong> - MetaMask, Phantom, Rabby
      </li>
    </ul>

    <br />

    <strong>Benefits of Controller:</strong>

    <ul
      style={{
      paddingLeft: "1.5rem",
      marginTop: "0.5rem",
      listStyleType: "disc",
    }}
    >
      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        Gasless transactions for smooth gameplay
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        Social login convenience
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        Multi-platform access
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        Built specifically for gaming
      </li>
    </ul>
  </div>

  <div style={{ flex: "1", textAlign: "center" }}>
    <img
      src="/docs/lootsurvivor/controller-sign-up.png"
      alt="Controller sign-up interface"
      style={{
      width: "100%",
      maxWidth: "400px",
      borderRadius: "8px",
      border: "1px solid #333",
    }}
    />

    <em style={{ display: "block", marginTop: "0.5rem", fontSize: "0.9em" }}>
      Controller sign-up interface
    </em>
  </div>
</div>

#### Step 2: Connect and Purchase

<div
  style={{
  display: "flex",
  gap: "2rem",
  alignItems: "flex-start",
  margin: "1rem 0",
  flexWrap: "wrap",
}}
>
  <div style={{ flex: "1", minWidth: "300px" }}>
    <strong>Follow these steps:</strong>

    <ol
      style={{
      paddingLeft: "1.5rem",
      marginTop: "0.5rem",
      listStyleType: "decimal",
    }}
    >
      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        <strong>🌐 Visit Game</strong> - Navigate to lootsurvivor.io
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        <strong>🔗 Connect Wallet</strong> - Click "Login" and approve
        connection
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        <strong>🎟️ Buy Ticket</strong> - Purchase dungeon entry with crypto or
        credit card (see <a href="/lootsurvivor/dungeon-tickets">Dungeon Tickets</a> for details)
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        <strong>⚔️ Start Adventure</strong> - Create your adventurer
      </li>
    </ol>

    <br />

    <strong>Pro Tips:</strong>

    <ul
      style={{
      paddingLeft: "1.5rem",
      marginTop: "0.5rem",
      listStyleType: "disc",
    }}
    >
      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        Keep some funds for multiple games
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        Ticket prices vary based on demand
      </li>

      <li style={{ marginBottom: "0.25rem", display: "list-item" }}>
        Your progress saves to the blockchain
      </li>
    </ul>
  </div>

  <div style={{ flex: "1", textAlign: "center" }}>
    <img
      src="/docs/lootsurvivor/ticket-purchase.png"
      alt="Dungeon ticket purchase interface"
      style={{
      width: "100%",
      maxWidth: "400px",
      borderRadius: "8px",
      border: "2px solid #333",
    }}
    />

    <em style={{ display: "block", marginTop: "0.5rem", fontSize: "0.9em" }}>
      Dungeon ticket purchase interface
    </em>
  </div>
</div>

***

## Your First Adventure

### Understanding Your Adventurer

When you create a new adventurer, you'll receive:

* **⚔️ Starting Weapon** - Random Tier 5 weapon
* **📊 Base Stats** - 12 points randomly distributed
* **❤️ Health** - 100 HP + VIT bonus

### Core Game Loop

The adventure follows a simple cycle:

1. **🔍 Explore** - Search for items, gold, and XP
2. **⚔️ Combat** - Fight or flee from beasts
3. **📈 Level Up** - Allocate stat points
4. **🛍️ Market** - Buy equipment and potions
5. **🔄 Repeat** - Continue deeper into Death Mountain

**Goal:** Survive as long as possible!

### Game Interface Overview

#### Main HUD Elements

| Element         | Icon | Description                   | Location     |
| --------------- | ---- | ----------------------------- | ------------ |
| **Health Bar**  | ❤️   | Current HP (100 + VIT bonus)  | Top left     |
| **XP Progress** | ⭐    | Experience toward next level  | Below health |
| **Gold**        | 🪙   | Currency for market purchases | Top right    |
| **Equipment**   | 🛡️  | 8 equipped item slots         | Center panel |
| **Inventory**   | 🎒   | 15 additional storage slots   | Right panel  |

#### Action Controls

* **🔍 Explore** - Continue deeper into the dungeon
* **⚔️ Attack** - Fight beasts you encounter
* **🏃 Flee** - Escape from combat encounters
* **📈 Upgrade** - Allocate stat points when available
* **🛍️ Market** - Buy equipment and potions

***

## Community & Support

Join the Loot Survivor community:

* **💬 Discord:** [discord.gg/lootsurvivor](https://discord.gg/Q36rUxS66c)
* **🐦 Twitter:** [@lootsurvivor](https://twitter.com/lootsurvivor)
* **🐙 GitHub:** [Report Issues](https://github.com/Provable-Games/death-mountain/issues)

***

## Ready to Begin?

Every adventure is unique, every death is permanent, and every decision matters. Start with **Practice Mode** to learn the basics, then upgrade to **Beast Mode** for the full blockchain experience!


## Loot Survivor: Guide

Welcome to the Loot Survivor guide! Here you'll find everything you need to get started and master the core mechanics. Whether you're a new adventurer or looking to understand the game systems, this guide covers the essential aspects of gameplay.

### Table of Contents

* [Getting Started](/lootsurvivor/guide/getting-started): Setting up your wallet and starting your first adventure
* [Explore](/lootsurvivor/guide/explore): Navigating the dungeon and discovering challenges
* [Battle](/lootsurvivor/guide/battle): Combat mechanics and defeating beasts
* [Upgrade](/lootsurvivor/guide/upgrade): Leveling up and stat allocation

### Overview

Loot Survivor is a fully onchain dungeon crawler roguelike where every decision could be your last. In this guide, you'll learn:

1. **How to onboard and set up your wallet** for seamless play on Starknet
2. **The core gameplay loop**—from exploring dungeons to battling beasts
3. **How to allocate stats** when leveling up your adventurer
4. **Combat mechanics** including type advantages and battle actions

Each section provides clear explanations and visuals to help you understand the game mechanics. Dive in and start your journey!


## Upgrade Guide

Leveling up and upgrading your adventurer is a pivotal moment in every Loot Survivor run. Each level brings stat points to allocate and opens the market with fresh items. Master the upgrade system to transform your adventurer from a fragile newcomer into an unstoppable force!

> **⚡ Power Spike:** Every level up is an opportunity to dramatically increase your power. Plan your upgrades carefully!

### Upgrade Overview

The upgrade system consists of three key components:

1. **Stat Allocation** - Distribute points to enhance your adventurer's capabilities
2. **Market Refresh** - Access new items with each level up
3. **Purchase Decisions** - Buy equipment and potions from the market

### Upgrade Interface

<div style={{ maxWidth: "900px", margin: "2rem auto" }}>
  <img
    src="/docs/lootsurvivor/upgrade.png"
    alt="Loot Survivor Upgrade Screen"
    style={{
    width: "100%",
    display: "block",
    margin: "0 auto",
    borderRadius: "8px",
    border: "2px solid #333",
  }}
  />

  <br />

  <em style={{ display: "block", textAlign: "center" }}>
    Figure: Upgrade interface with stat menu
  </em>
</div>

***

## Stat Allocation

### Stat Point Distribution

You receive **1 stat point per level** to allocate among:

| Stat     | Effect per Point               | Primary Use          |
| -------- | ------------------------------ | -------------------- |
| **STR**  | +10% attack damage             | Combat damage        |
| **DEX**  | Improves flee success          | Escaping from beasts |
| **VIT**  | +15 HP max & current           | Health and survival  |
| **INT**  | Aids obstacle avoidance        | Avoiding obstacles   |
| **WIS**  | Helps evade beast ambushes     | Ambush prevention    |
| **CHA**  | Gold discount on items/potions | Market purchases     |
| **LUCK** | ❌ Cannot upgrade               | Item discovery only  |

> **🎯 Allocation Note:** Consider focusing on 2-3 primary stats rather than spreading points evenly across all stats.

***

## Market System

### How Markets Generate

<div
  style={{
backgroundColor: "rgba(59, 130, 246, 0.1)",
border: "2px solid #3b82f6",
borderRadius: "8px",
padding: "1.5rem",
marginBottom: "2rem",
marginTop: "2rem"
}}
>
  <h3 style={{ marginTop: 0, marginBottom: "1rem", color: "#3b82f6" }}>🎲 Market Generation Mechanics</h3>

  <p style={{ marginBottom: "1rem" }}>
    Each level up generates a unique market through random selection:
  </p>

  <ul style={{ marginBottom: 0 }}>
    <li style={{ marginBottom: "0.75rem" }}>
      <strong>25 Rolls:</strong> The game rolls for 25 random items
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      <strong>No Duplicates:</strong> If the same item is rolled multiple times, it only appears once
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Variable Size:</strong> Markets can have 1-25 items depending on duplicate rolls
    </li>

    <li style={{ marginBottom: "0.75rem" }}>
      <strong>Level Locked:</strong> The same market persists for your entire level
    </li>

    <li>
      <strong>Fresh on Level Up:</strong> New random items appear when you reach the next level
    </li>
  </ul>
</div>

#### Market Contents

Markets can contain:

* **⚔️ Weapons** - All tiers and types
* **🛡️ Armor** - Head, chest, waist, foot, and hand pieces
* **💍 Jewelry** - Rings and necklaces for stat boosts
* **🧪 Potions** - Health and other consumables

#### Market Strategy

* **Check Everything:** With limited rolls, valuable items might be rare
* **Plan Purchases:** The market won't refresh until next level
* **CHA Benefits:** Higher Charisma reduces all market prices
* **Gold Management:** Save for critical upgrades vs. immediate needs

> **💡 Pro Tip:** A small market (few items) means many duplicate rolls occurred. Don't expect it to have everything you need!


## Beast Collectibles

In **Beast Mode** defeating uncollected named beasts in Loot Survivor will mint an NFT to your wallet. There is a fixed supply of **93,225** uniquely generated Beasts across **75 species** (1,243 variants per species) to be collected.

<div style={{ display: 'flex', gap: '1rem', margin: '2rem 0', textAlign: 'center', flexWrap: 'wrap', justifyContent: 'center' }}>
  <div>
    <img
      src="/docs/lootsurvivor/warlock_regular_static.svg"
      alt="Warlock Regular Static"
      style={{
    width: "200px",
    height: "200px",
    margin: "0 auto",
    borderRadius: "12px",
  }}
    />

    <p style={{ fontSize: "0.9rem", margin: "0", opacity: "0.9" }}>
      Regular Static
    </p>
  </div>

  <div>
    <img
      src="/docs/lootsurvivor/warlock_shiny_static.svg"
      alt="Warlock Shiny Static"
      style={{
    width: "200px",
    height: "200px",
    margin: "0 auto",
  }}
    />

    <p style={{ fontSize: "0.9rem", margin: "0", opacity: "0.9" }}>
      Shiny Static
    </p>
  </div>

  <div>
    <img
      src="/docs/lootsurvivor/warlock_regular_animated.svg"
      alt="Warlock Regular Animated"
      style={{
    width: "200px",
    height: "200px",
    margin: "0 auto",
  }}
    />

    <p style={{ fontSize: "0.9rem", margin: "0", opacity: "0.9" }}>
      Regular Animated
    </p>
  </div>

  <div>
    <img
      src="/docs/lootsurvivor/warlock_shiny_animated.svg"
      alt="Warlock Shiny Animated"
      style={{
    width: "200px",
    height: "200px",
    margin: "0 auto",
  }}
    />

    <p style={{ fontSize: "0.9rem", margin: "0", opacity: "0.9" }}>
      Shiny Animated
    </p>
  </div>
</div>

### Beast Mode NFT System

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '2rem 0', lineHeight: '1.6' }}>
  **NFT Minting:** Defeating uncollected named beasts automatically mints collectible NFTs to your wallet

  **Beast Mode Features:**

  * **Named Beast Focus**: Only special named beasts (Level 19+) mint NFTs
  * **First Victory Bonus**: NFTs only mint on first defeat of each named beast
  * **Automatic Collection**: No manual claiming - NFTs appear directly in your wallet
  * **Permanent Ownership**: Each NFT represents a unique named beast victory

  > **Collect Them All:** Build your personal gallery of defeated legendary named beasts!
</div>

### Collection Overview

<div style={{ background: '#0f172a', padding: '1.25rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.7', border: '1px solid #334155' }}>
  * **Fully onchain artwork + metadata**: Images and JSON are generated and rendered directly from smart contracts
  * **Born onchain**: Beasts are earned in Loot Survivor using verifiable randomness; every step is recorded onchain
  * **Battle‑ready NFTs**: Each Beast mints with combat stats (level, health), type, and tier compatible with gameplay
  * **Live ranking within species**: Each species tracks ranks #1–#1,243 as they mint; when complete, a King Beast is crowned
  * **Credibly neutral traits**: Onchain state includes defeat timestamp and the last Adventurer to slay that Beast
</div>

#### 🎨 NFT Visual Rarity & Properties

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.8' }}>
  <div style={{ marginBottom: '1.5rem' }}>
    **NFT Visual Rarities:**
  </div>

  <div style={{ marginBottom: '1rem' }}>
    | Visual Type          | Rarity Chance | Description                | Collection Value |
    | -------------------- | ------------- | -------------------------- | ---------------- |
    | **Standard**         | 89.75%        | Regular static beast image | Base             |
    | **Animated**         | 5%            | Moving/animated beast NFT  | Rare             |
    | **Shiny**            | 5%            | Shimmering visual effects  | Rare             |
    | **Animated + Shiny** | 0.25%         | Both animated AND shiny    | Ultra Rare       |
  </div>

  <div style={{ marginBottom: '1.5rem' }}>
    **NFT Metadata (All Beasts Include):**
  </div>

  <div style={{ marginBottom: '0' }}>
    * **Level & Health**: Combat stats encoded at mint
    * **Tier & Type**: T1–T5 tier and one of Magical, Hunter, Brute
    * **Name & Prefix**: Base species name plus optional prefix (e.g., "Doom Kraken")
    * **Defeat Timestamp**: Onchain record of when the Beast was defeated
    * **Provenance Fields**: Credibly neutral traits like last slayer enable onchain leaderboards and history
  </div>
</div>

### NFT Minting Requirements

<div style={{ background: '#2a2a1a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #eab308', margin: '1rem 0', lineHeight: '1.6' }}>
  #### Named Beast NFT Mechanics

  **Level Requirement:** Only beasts level 19+ can gain special names and be collected\
  **Name Structure:** \[Prefix] \[Suffix] \[Beast Name] = Unique NFT\
  **Example:** "Doom Shadow" Kraken and "Demon Moon" Kraken mint as separate collectibles

  #### NFT Minting Rules

  **First Victory Only:** Each named beast can only mint one NFT per wallet\
  **Automatic Process:** No manual claiming - NFT appears immediately after victory\
  **Unique Metadata:** Each NFT contains beast stats, prefix, and victory timestamp\
  **Permanent Record:** NFTs serve as proof of your legendary victories

  > **Complete Reference:** Visit the loot section for the full categorized list of all 69 prefixes!
</div>

### Tier Logo Colors

<div style={{ background: '#1a1a1a', padding: '1rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.6' }}>
  * **Tier 1 (Legendary)**: Orange logo — most powerful
  * **Tier 2 (Epic)**: Purple logo
  * **Tier 3 (Rare)**: Blue logo
  * **Tier 4 (Uncommon)**: Green logo
  * **Tier 5 (Common)**: White logo
</div>

### Contract & Source Code

* [Mainnet Contract](https://voyager.online/nft-contract/0x046da8955829adf2bda310099a0063451923f02e648cf25a1203aac6335cf0e4)
* [Source Code](https://github.com/Provable-Games/beasts/tree/v1.0.1)

### NFT Ownership Benefits

#### Digital Asset Value

* **True Ownership**: NFTs belong to you, not the game
* **Transferable Assets**: Trade or sell your named beast NFTs
* **Provable Rarity**: Onchain verification of NFT scarcity
* **Permanent Record**: Victory achievements stored forever on Starknet

***

*The Beasts are a generative art collection where the algorithm is the decisions of the adventurers in the Loot Survivor dungeon.*

### See Also

* [Beast Overview](/lootsurvivor/beasts) - Complete beast guide and combat types
* [Combat Mechanics](/lootsurvivor/combat) - Damage calculations and combat system
* [Battle Guide](/lootsurvivor/guide/battle) - Tactical combat strategies


## Beasts

Beasts are the creatures you'll encounter and battle throughout your adventures in Loot Survivor. Understanding beast types, tiers, and combat advantages is crucial for survival and progression.

### Beast Overview

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '2rem 0', lineHeight: '1.8' }}>
  <div style={{ marginBottom: '1rem' }}>
    **75 unique beasts** populate Loot Survivor, each with distinct characteristics:
  </div>

  <div style={{ marginBottom: '1rem' }}>
    * **3 Combat Types**: Magical, Hunter, and Brute
    * **5 Tiers**: T1 (Legendary) to T5 (Common)
    * **Special Names**: High-level beasts gain name prefixes at level 19+
    * **Dynamic Generation**: Each encounter uses VRF seeds for true randomness
  </div>

  > **Combat Focus:** Every beast follows the rock-paper-scissors combat system - choose your equipment wisely!
</div>

### Beast Tier System

<div style={{ background: '#1a1a1a', padding: '1.5rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.6' }}>
  | Tier   | Rarity      | Power Level | Gold Reward | XP Reward | Examples                 |
  | ------ | ----------- | ----------- | ----------- | --------- | ------------------------ |
  | **T1** | Legendary   | Highest     | 5× level    | Maximum   | Warlock, Griffin, Kraken |
  | **T2** | Rare        | High        | 4× level    | High      | Gorgon, Qilin, Titan     |
  | **T3** | Uncommon    | Medium      | 3× level    | Medium    | Werewolf, Wyvern, Oni    |
  | **T4** | Common      | Low         | 2× level    | Low       | Goblin, Fenrir, Yeti     |
  | **T5** | Very Common | Lowest      | 1× level    | Minimum   | Fairy, Bear, Troll       |

  **Reward Formula:** Gold = (Tier Multiplier × Beast Level) ÷ 2
</div>

### Beast Categories

#### 🪄 Magical Beasts (25 Total)

<div style={{ background: '#2a1a3e', padding: '1rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.6' }}>
  **T1 Legendary (5):** Warlock, Typhon, Jiangshi, Anansi, Basilisk\
  **T2 Rare (5):** Gorgon, Kitsune, Lich, Chimera, Wendigo\
  **T3 Uncommon (5):** Rakshasa, Werewolf, Banshee, Draugr, Vampire\
  **T4 Common (5):** Goblin, Ghoul, Wraith, Sprite, Kappa\
  **T5 Very Common (5):** Fairy, Leprechaun, Kelpie, Pixie, Gnome
</div>

#### 🏹 Hunter Beasts (25 Total)

<div style={{ background: '#2a3e1a', padding: '1rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.6' }}>
  **T1 Legendary (5):** Griffin, Manticore, Phoenix, Dragon, Minotaur\
  **T2 Rare (5):** Qilin, Ammit, Nue, Skinwalker, Chupacabra\
  **T3 Uncommon (5):** Weretiger, Wyvern, Roc, Harpy, Pegasus\
  **T4 Common (5):** Hippogriff, Fenrir, Jaguar, Satori, Direwolf\
  **T5 Very Common (5):** Bear, Wolf, Mantis, Spider, Rat
</div>

#### 🔨 Brute Beasts (25 Total)

<div style={{ background: '#3e1a1a', padding: '1rem', borderRadius: '8px', margin: '1rem 0', lineHeight: '1.6' }}>
  **T1 Legendary (5):** Kraken, Colossus, Balrog, Leviathan, Tarrasque\
  **T2 Rare (5):** Titan, Nephilim, Behemoth, Hydra, Juggernaut\
  **T3 Uncommon (5):** Oni, Jotunn, Ettin, Cyclops, Giant\
  **T4 Common (5):** Nemeanlion, Berserker, Yeti, Golem, Ent\
  **T5 Very Common (5):** Troll, Bigfoot, Ogre, Orc, Skeleton
</div>

### Special Beast Names

<div style={{ background: '#2a2a1a', padding: '1.5rem', borderRadius: '8px', border: '1px solid #eab308', margin: '1rem 0', lineHeight: '1.8' }}>
  #### Naming System

  <div style={{ marginBottom: '1rem' }}>
    High-level beasts (Level 19+) can gain **special name prefixes** that provide:
  </div>

  <div style={{ marginBottom: '1.5rem' }}>
    * **Enhanced Combat Power**: Named beasts are significantly stronger
    * **Bonus Rewards**: Higher gold and XP rewards
    * **Collectible Value**: Named beast encounters become permanent achievements
  </div>

  #### Example Names

  <div style={{ marginBottom: '1rem' }}>
    **Prefix Examples:** Agony, Apocalypse, Armageddon, Beast, Behemoth, Blood, Death, Demon, Doom, Dragon
  </div>

  <div style={{ marginBottom: '1rem' }}>
    **Full Named Beast:** "**Doom** **Phoenix**" or "**Blood** **Kraken**"
  </div>

  > **Pro Tip:** Named beasts are dangerous but offer the best rewards and collectible potential!
</div>

### Beast Encounter Mechanics

<div style={{ background: '#1a2332', padding: '1.5rem', borderRadius: '8px', border: '1px solid #3b82f6', margin: '1rem 0', lineHeight: '1.6' }}>
  #### Generation System

  * **VRF Seeds**: True randomness for beast selection (configurable in settings)
  * **Level Scaling**: Beast power increases with your adventurer level
  * **Tier Distribution**: Higher tiers become more common at lower levels
  * **Special Names**: 19+ level beasts can gain name prefixes randomly

  #### Combat Rewards

  ```
  Gold Reward = (Tier Multiplier × Beast Level) ÷ 2
  XP Reward = Minimum 4 + beast tier bonuses
  ```

  **Bonus Multipliers:**

  * Critical hits from LUCK stat
  * Name match bonuses (weapon/armor names matching beast names)
  * Type advantage damage (+50%)
</div>

### See Also

* [Combat Mechanics](/lootsurvivor/combat) - Detailed damage calculations
* [Battle Guide](/lootsurvivor/guide/battle) - Combat tactics and interface
* [Loot System](/lootsurvivor/loot) - Equipment and weapons
* [Beast Collectibles](/lootsurvivor/beasts/collectibles) - Achievement system
* [Wanted Beasts](/lootsurvivor/beasts/wanted-beasts) - Special bounties with STRK rewards


## Wanted Beasts

### Starkware & Cartridge Partnership

Loot Survivor has partnered with Starkware and Cartridge to bring an exclusive promotion featuring 100,000 STRK tokens distributed across three legendary Beasts. This collaboration celebrates the launch of SURVIVOR and rewards the most skilled adventurers who can defeat these special creatures.

#### Prize Distribution

The 100,000 STRK prize pool is split between three unique Beasts, each offering substantial rewards to the adventurer who claims victory:

<div style={{display: "flex", alignItems: "center", justifyContent: "center", marginBottom: "3rem"}}>
  <img src="/docs/lootsurvivor/jackpot_balrog.png" alt="Torment Bane Balrog" style={{width: "200px", marginRight: "2rem"}} />

  <div>
    <h4>"Torment Bane" Balrog</h4>

    <ul>
      <li><strong>STRK Reward</strong>: 33,333 STRK</li>
      <li><strong>Location</strong>: The Molten Depths</li>
      <li><strong>Special Traits</strong>: Ancient demon of fire and shadow, Wielder of eternal flames</li>
    </ul>
  </div>
</div>

<div style={{display: "flex", alignItems: "center", justifyContent: "center", marginBottom: "3rem"}}>
  <img src="/docs/lootsurvivor/jackpot_warlock.png" alt="Pain Whisper Warlock" style={{width: "200px", marginRight: "2rem"}} />

  <div>
    <h4>"Pain Whisper" Warlock</h4>

    <ul>
      <li><strong>STRK Reward</strong>: 33,333 STRK</li>
      <li><strong>Location</strong>: The Shadow Sanctum</li>
      <li><strong>Special Traits</strong>: Master of dark arts, Collector of tormented souls</li>
    </ul>
  </div>
</div>

<div style={{display: "flex", alignItems: "center", justifyContent: "center", marginBottom: "3rem"}}>
  <img src="/docs/lootsurvivor/jackpot_dragon.png" alt="Demon Grasp Dragon" style={{width: "200px", marginRight: "2rem"}} />

  <div>
    <h4>"Demon Grasp" Dragon</h4>

    <ul>
      <li><strong>STRK Reward</strong>: 33,334 STRK</li>
      <li><strong>Location</strong>: The Dragon's Lair</li>
      <li><strong>Special Traits</strong>: Guardian of ancient treasures, Corrupted by demonic influence</li>
    </ul>
  </div>
</div>

#### How It Works

1. **Find the Beast**: These special Beasts spawn randomly in the dungeon
2. **Defeat to Claim**: The first adventurer to defeat each Beast claims the STRK reward
3. **Automatic Distribution**: STRK tokens are automatically sent to the winning adventurer's wallet
4. **One Winner per Beast**: Each Beast can only be defeated once for the reward

#### Promotion Period

This promotion runs indefinitely. These special Beasts will continue to spawn in the dungeon, offering adventurers ongoing opportunities to claim the STRK rewards. The promotion remains active until all three unique Beasts have been defeated and the full 100,000 STRK has been distributed.

#### About Our Partners

**Starkware** - The technology company behind Starknet, providing the scalable infrastructure that powers Loot Survivor's fully onchain gameplay.

**Cartridge** - The gaming infrastructure platform enabling seamless wallet experiences and player onboarding for Starknet games.

This partnership demonstrates the strong ecosystem support for Loot Survivor and commitment to rewarding skilled players with meaningful prizes.


## Embeddable Game Standard: Applications

The Embeddable Game Standard (EGS) unlocks powerful new possibilities for both game developers and platforms. By making games permissionlessly embeddable, EGS enables a growing ecosystem of apps to integrate, distribute, and build on top of games in novel ways. This page highlights some of the leading apps leveraging EGS today.

### Budokan: Permissionless Tournaments

Budokan uses the EGS to provide a fully permissionless tournament protocol. With EGS, games no longer need to implement their own leaderboard or revenue logic—instead, they can plug into Budokan's aggregated platform, which:

* Accepts any supported token for entry fees and prizes
* Offers extensive customization for tournament formats, entry requirements, and prize structures
* Handles all leaderboard, prize, and entry logic on behalf of the game

This makes it easy for game developers to reach new audiences and for players to discover and compete in a wide variety of tournaments.

![Budokan Overview](/docs/overview.png)
*Figure 1: Budokan overview page.*

> **Tip:** By integrating with Budokan, game developers can focus on gameplay while the platform handles tournaments, rewards, and community engagement.

### Eternum: Expanding Gameplay with Embedded Mini-Games

Eternum, a next-generation MMO, leverages EGS to embed mini-games directly into its core experience. In Season 1, Eternum introduced a new quest system powered by EGS, allowing:

* Seamless integration of third-party mini-games as quests
* Emergence of new strategies and gameplay loops
* A more dynamic, deconstructed MMO experience

![Eternum Quest](/docs/eternum-quest.png)
*Figure 2: Eternum Quest.*

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>
      Embedding games within Eternum allows mini-games to reach a much wider audience, maximizing their distribution and exposure. For Eternum, this approach brings significant value by introducing a diverse range of gameplay experiences to their core player base, keeping the platform fresh and engaging. By integrating a variety of mini-games, Eternum can continually offer new challenges and entertainment, enhancing player retention and satisfaction.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/eternum-quest-post.png" alt="Eternum Quest Post" width="400" height="300" />

    <br />

    <em>Figure 3: Eternum Quest Post.</em>
  </div>
</div>

> **Note:** EGS makes it easy for any platform to embed, remix, or build on top of games, opening up new opportunities for both developers and communities.

### Why Build Applications with EGS?

* Offer a diverse library of games and experiences
* Easily add new content and features without building from scratch
* Foster engagement and retention by providing variety to your users

> **Tip:** The EGS ecosystem is growing—consider how your app or game could benefit from permissionless embedding and integration.

### Related Guides

* [Embeddable Game Standard Overview](/embeddable-game-standard)
* [Budokan Tournaments](/budokan)
* [Game Integration Guide](/embeddable-game-standard/implementation)

If you have questions or want to feature your app here, contact the Budokan team or join the community!


## Embeddable Game Standard: FAQ

Developer-oriented FAQ for the Embeddable Game Standard (EGS) on Starknet.

### General

**What is the Embeddable Game Standard?**

EGS is a standard interface for Starknet games that enables interoperability across platforms. It standardizes game contract functionalities including ERC721 token minting, metadata management, score tracking, and settings — so any compliant game can be embedded in any compliant platform.

**What problem does EGS solve?**

Without EGS, each game needs custom integration for every platform. EGS provides a common interface so games can be listed in tournaments, embedded in other applications, and tracked on leaderboards without per-game integration work.

**What games currently use EGS?**

Dark Shuffle, Loot Survivor, zKube, Nums, and Dope Wars all implement the EGS interface.

### Integration

**How do I implement EGS in my game?**

1. Add the tournaments dependency to your `Scarb.toml`: `tournaments = { git = "https://github.com/Provable-Games/tournaments.git", tag = "v1.5.0" }`
2. Import and embed the `game_component` in your contract
3. Implement required storage and events (Game, ERC721, SRC5)
4. Expose required interfaces: ERC721, metadata, and settings
5. Call `initializer()` during contract setup with your game's metadata

See the [Implementation Guide](/embeddable-game-standard/implementation) for a full walkthrough.

**What are the key functions I need to implement?**

* `mint(player_name, settings_id, start, end, to)` — Mint a new game instance as an ERC721 token
* `game_metadata()` — Return game contract metadata (name, description, developer, etc.)
* `token_metadata(token_id)` — Return metadata for a specific game token
* `score(game_id)` — Return a player's score for validation and leaderboards
* `setting_exists(settings_id)` — Check if a settings profile exists
* `emit_metadata_update(game_id)` — Emit event for offchain indexing

Full reference: [Key Functions](/embeddable-game-standard/key-functions).

**What is the settings system?**

Settings allow custom game modes by linking a unique `settings_id` to each game instance. They enable difficulty levels, speedruns, seasonal events, and community challenges. Settings are stored onchain and are composable across games, quests, and tournaments. See: [Game Settings](/embeddable-game-standard/implementation/settings).

**How do platforms embed my game?**

Platforms call `mint()` on your game contract to create a game instance (a unique onchain token) for each player. They then call `score()` to validate results for leaderboards and prizes. See: [Embedding Games](/embeddable-game-standard/implementation/embedding-games).

### Platforms

**What platforms support EGS games?**

* **Budokan**: Permissionless tournament protocol. Any EGS game can be used in tournaments with custom entry fees and prize pools.
* **Eternum**: MMO that embeds EGS games as quests, extending gameplay through mini-game integrations.

**What are the benefits for game developers?**

Reach new audiences without building platform integrations. Your game can be used in tournaments, embedded as quests, and listed across multiple applications. Focus on gameplay and innovation rather than infrastructure.

**What are the benefits for platform developers?**

Access a library of onchain games without building from scratch. Add new content and engagement through variety. Each game instance is a unique, verifiable onchain token.

### More Resources

* [Overview](/embeddable-game-standard)
* [Key Functions](/embeddable-game-standard/key-functions)
* [Implementation Guide](/embeddable-game-standard/implementation)
* [Games](/embeddable-game-standard/games)
* [Applications](/embeddable-game-standard/applications)


import { GameCard } from "../../components/GameCard";

## Embeddable Game Standard: Games

Here is a list of games that have implemented the embeddable game standard and are benefitting from the tools provided:

<GameCard icon="https://darkshuffle.io/favicon.svg" name="Dark Shuffle" url="https://darkshuffle.io" description="Dark Shuffle is a turn-based, collectible card game. Build your deck, battle monsters, and explore a procedurally generated world." developer="Provable Games" />

<GameCard icon="https://app.zkube.xyz/assets/pwa-512x512.png" name="zKube" url="https://app.zkube.xyz/" description="zKube is an engaging puzzle game that puts players' strategic thinking to the test. Set within a dynamic grid, the objective is simple: manipulate blocks to form solid lines and earn points.	" developer="zKorp" />

<GameCard icon="https://raw.githubusercontent.com/Provable-Games/death-mountain/main/client/public/images/skull.png" name="Loot Survivor" url="https://lootsurvivor.io" description="Fight for your life against treacherous beasts and obstacles in search of mythical loot in this procedurally generated dungeon crawler." developer="Provable Games" />

<GameCard icon="https://raw.githubusercontent.com/cartridge-gg/nums/main/public/favicon.svg" name="Nums" url="https://nums.gg" description="Nums is a sequential puzzle game where players sequence a series of 20 generated numbers. The first layer-3 appchain built on Starknet." developer="Cartridge" />

<GameCard icon="https://raw.githubusercontent.com/cartridge-gg/dopewars/main/assets/icon.png" name="Dope Wars" url="https://rollyourown.preview.cartridge.gg/" description="A decentralized, hip-hop culture-infused on-chain metaverse inspired by the classic Drug Wars and GTA series, where players engage in strategic gameplay using NFTs." developer="Dope Wars DAO" />

### Why Build Games with EGS?

* Instantly reach new audiences by making your game embeddable in multiple apps and platforms
* Focus on gameplay and innovation, not infrastructure
* Extend the way your game is played through permissionless settings creation
* Benefit from community-driven tournaments, quests, and rewards


## Embeddable Game Standard

The Embeddable Game Standard (EGS) is a foundational blueprint for Starknet games, designed to ensure interoperability and unlock access to an ever-growing ecosystem of powerful onchain applications, including the [Budokan](/budokan) tournament platform and the Tanken Quest platform (coming soon). It standardizes essential game contract functionalities such as ERC721 token minting for unique game instances, comprehensive metadata management, and robust score or progress tracking, which are vital for both competitive play and objective-based questing. By adhering to EGS, games can be seamlessly integrated into systems that distribute game instances as NFTs, associate them with diverse rewards (for victory, completion, or participation), and support varied engagement models. From high-stakes tournaments to narrative-driven campaigns, onboarding tutorials, and community-tailored challenges.

### Table of Contents

* [Overview](#overview)
* [Architecture](#architecture)
* [Key Functions](#key-functions)
* [Implementation Guide](#implementation-guide)

### Overview

The standard provides a blueprint for game contracts to:

* Mint game tokens (ERC721) for tournament entries
* Store and expose game and player metadata
* Track scores and settings in a standardized way
* Emit events for metadata updates and lifecycle changes

By adhering to this standard, games can:

* Be listed and used in Budokan tournaments
* Enable automated leaderboard and prize logic
* Support composable, upgradable tournament experiences

### Architecture

* **Game Component:** Implements the core logic for minting, metadata management, and score tracking. See `contracts/src/components/game.cairo`.
* **Models & Interfaces:** Define the data structures for game metadata, token metadata, settings, and lifecycle events.
* **Integration Points:** Games must expose the required interfaces and implement the necessary storage and event logic.

### Key Functions

* `mint`: Mint a new game token for a player, with associated metadata and settings.
* `game_metadata`: Retrieve metadata for the game contract.
* `token_metadata`: Retrieve metadata for a specific game token.
* `game_count`: Get the total number of games/tokens minted.
* `emit_metadata_update`: Emit an event when token metadata is updated.
* `initializer`: Initialize the game contract with metadata, settings, and storage configuration.

### Implementation Guide

1. **Implement the Game Component:**
   * Use the provided `game_component` module as a base.
   * Implement the required storage, events, and interface functions.
2. **Define Metadata and Settings:**
   * Use the standard models for game and token metadata.
   * Store settings and score models as required by your game logic.
3. **Integrate with Budokan:**
   * Ensure your contract exposes the required interfaces (ERC721, metadata, settings).
   * Test minting, metadata retrieval, and event emission with Budokan tournament flows.
4. **Deploy and Register:**
   * Deploy your game contract to Starknet.
   * Register the game with Budokan for tournament use.

### Games

The current games that have implemented the standard:

* Dark Shuffle
* Zkube
* Loot Survivor (coming soon)

By following this standard, your game will be compatible with Budokan and other systems that adopt the Embeddable Game Standard.


## Embeddable Game Standard: Key Functions

This section details the primary functions that a game contract must implement to comply with the Embeddable Game Standard and be compatible with Budokan tournaments.

### `mint`

```cairo
fn mint(
    ref self: ComponentState<TContractState>,
    player_name: felt252,
    settings_id: u32,
    start: Option<u64>,
    end: Option<u64>,
    to: ContractAddress,
) -> u64;
```

**Purpose:** Mint a new game token (ERC721) for a player, with associated metadata and settings.

**Parameters:**

* `player_name`: Name of the player (felt252).
* `settings_id`: ID of the game settings to use.
* `start`, `end`: Optional start and end timestamps for the game session.
* `to`: Address to mint the token to.

**Returns:** Token ID of the newly minted game token.

***

### `game_metadata`

```cairo
fn game_metadata(self: @ComponentState<TContractState>) -> GameMetadata;
```

**Purpose:** Retrieve metadata for the game contract (name, description, developer, etc.).

**Returns:** GameMetadata struct.

***

### `token_metadata`

```cairo
fn token_metadata(self: @ComponentState<TContractState>, token_id: u64) -> TokenMetadata;
```

**Purpose:** Retrieve metadata for a specific game token (player, settings, lifecycle, etc.).

**Parameters:**

* `token_id`: ID of the game token.

**Returns:** TokenMetadata struct.

***

### `game_count`

```cairo
fn game_count(self: @ComponentState<TContractState>) -> u64;
```

**Purpose:** Get the total number of games/tokens minted by the contract.

**Returns:** Total count (u64).

***

### `emit_metadata_update`

```cairo
fn emit_metadata_update(ref self: ComponentState<TContractState>, game_id: u64);
```

**Purpose:** Emit an event when token metadata is updated, for offchain indexing and UI updates.

**Parameters:**

* `game_id`: ID of the game token whose metadata was updated.

***

### `initializer`

```cairo
fn initializer(
    ref self: ComponentState<TContractState>,
    creator_address: ContractAddress,
    name: felt252,
    description: ByteArray,
    developer: felt252,
    publisher: felt252,
    genre: felt252,
    image: ByteArray,
    namespace: ByteArray,
    score_model: ByteArray,
    score_attribute: ByteArray,
    settings_model: ByteArray,
);
```

**Purpose:** Initialize the game contract with metadata, settings, and storage configuration. Mints a creator token and registers interfaces.

**Parameters:**

* `creator_address`: Address of the game creator.
* `name`, `description`, `developer`, `publisher`, `genre`, `image`: Metadata fields.
* `namespace`, `score_model`, `score_attribute`, `settings_model`: Storage and configuration fields.

***

### Additional Functions

* `namespace`: Returns the namespace used for storage.
* `score_model`: Returns the score model identifier.
* `score_attribute`: Returns the score attribute identifier.
* `settings_model`: Returns the settings model identifier.
* `set_settings`: Set or update game settings details.
* `assert_setting_exists`: Ensure a settings ID exists before minting.


## Embeddable Game Standard: Embedding Games

Easily integrate onchain games into your own application or platform using the Embeddable Game Standard (EGS). This guide walks you through the process of minting a game instance for a player and validating their results, with code examples and best practices.

### What Does "Embedding" Mean?

Embedding a game means allowing your users to launch, play, and track progress in a provable onchain game—directly from your app. You can mint new game instances, monitor scores, and even run tournaments or quests using these standards.

### 1. Mint a Game Instance

To let a user start a new game, call the mint function on the game's contract. This creates a unique game token (NFT) for the player, with the desired settings and timing.

```cairo
use tournaments::components::interfaces::{
    IGameTokenDispatcher, IGameTokenDispatcherTrait,
};

let game_dispatcher = IGameTokenDispatcher { contract_address: quest_tile.game_address };
let game_token_id: u64 = game_dispatcher
    .mint(player_name, config.settings_id, game_start_delay, game_expiration, to_address);
```

* `player_name`: The player's display name or identifier.
* `settings_id`: The ID of the game settings profile to use (see [Settings](/embeddable-game-standard/implementation/settings)).
* `game_start_delay`: Optional delay before the game can be started.
* `game_expiration`: When the game expires (for time-limited quests or tournaments).
* `to_address`: The wallet address to receive the game token.

> **Tip:** Each minted game is a unique NFT, making it easy to track, transfer, or verify ownership and results.

### 2. Validate Game Results

To check a player's score or progress, use the `score` view function. This is enforced by the EGS and available on all compliant games.

```cairo
use tournaments::components::interfaces::{
    IGameDetailsDispatcher, IGameDetailsDispatcherTrait
};

let game_dispatcher = IGameDetailsDispatcher { contract_address: quest_tile.game_address };
let score: u32 = game_dispatcher.score(quest.game_token_id);
```

* `quest.game_token_id`: The unique token ID for the player's game instance.
* Returns the player's score or result, which you can use for leaderboards, rewards, or validation.

> **Info:** You can also query other view functions (like player stats, completion status, etc.) depending on the game's implementation. See the [View Functions](/embeddable-game-standard/implementation#6-add-view-functions) section for more.

### Best Practices & Next Steps

* Use the [Settings](/embeddable-game-standard/implementation/settings) standard to offer custom game modes or difficulty levels.
* Integrate with [Budokan](/budokan) for tournament management, prize distribution, and more.
* For advanced integrations, see the [Key Functions](/embeddable-game-standard/key-functions) and [Implementation Guide](/embeddable-game-standard/implementation).

If you have questions or want to see more examples, check the rest of the EGS docs or reach out to the community!


## Embeddable Game Standard: Implementation

This guide walks through the steps required for a game developer to implement the
Embeddable Game Standard and integrate with Budokan tournaments as well as any other meta apps.

### 1. Add EGS library

Start by adding the EGS library in your `Scarb.toml`. You will also need to build the external models to be included

```cairo
tournaments = { git = "https://github.com/Provable-Games/tournaments.git", tag = "v1.5.0" }
```

```cairo
build-external-contracts = [
    "tournaments::components::models::game::m_GameMetadata",
    "tournaments::components::models::game::m_TokenMetadata",
    "tournaments::components::models::game::m_GameCounter",
    "tournaments::components::models::game::m_Score",
    "tournaments::components::models::game::m_Settings",
    "tournaments::components::models::game::m_SettingsDetails",
    "tournaments::components::models::game::m_SettingsCounter",
]
```

### 2. Import Component

Import and use the `game_component` module from EGS.

```cairo
use tournaments::components::game::game_component;

#[dojo::contract]
pub mod MyGame {
    component!(path: game_component, storage: game, event: GameEvent);
    #[abi(embed_v0)]
    impl GameComponentImpl = game_component::GameImpl<ContractState>;
    impl GameComponentInternalImpl = game_component::InternalImpl<ContractState>;
    // ... additional game logic ...
}
```

### 3. Implement Required Storage and Events

Define the required storage fields and events as specified in the standard.

```cairo
#[storage]
struct Storage {
    #[substorage(v0)]
    game: game_component::Storage,
    #[substorage(v0)]
    erc721: ERC721Component::Storage,
    #[substorage(v0)]
    src5: SRC5Component::Storage,
}

#[event]
#[derive(Drop, starknet::Event)]
enum Event {
    #[flat]
    GameEvent: game_component::Event,
    #[flat]
    ERC721Event: ERC721Component::Event,
    #[flat]
    SRC5Event: SRC5Component::Event,
}
```

### 4. Expose Required Interfaces

Ensure your contract exposes the following:

* ERC721 interface for game tokens
* Metadata and settings interfaces
* Functions for minting, metadata retrieval, and event emission

### 5. Implement Initialization Logic

Implement the `initializer` function to set up game metadata, settings, and storage configuration.

```cairo
fn initializer(
    ref self: ComponentState<TContractState>,
    creator_address: ContractAddress,
    name: felt252,
    description: ByteArray,
    developer: felt252,
    publisher: felt252,
    genre: felt252,
    image: ByteArray,
    namespace: ByteArray,
    score_model: ByteArray,
    score_attribute: ByteArray,
    settings_model: ByteArray,
) {
    // ... initialization logic ...
}
```

### 6. Add View Functions

Add Contract view function to return the following:

* The score of a game id
* Whether a particular settings id exists

```cairo
use tournaments::components::interfaces::{IGameDetails, ISettings};

#[abi(embed_v0)]
impl GameDetailsImpl of IGameDetails<ContractState> {
    fn score(self: @ContractState, game_id: u64) -> u32 {
        let world: WorldStorage = self.world(@DEFAULT_NS());
        let game: Game = world.read_model(game_id);
        game.score.into()
    }
}

#[abi(embed_v0)]
impl SettingsImpl of ISettings<ContractState> {
    fn setting_exists(self: @ContractState, settings_id: u32) -> bool {
        let world: WorldStorage = self.world(@DEFAULT_NS());
        let settings: GameSettings = world.read_model(settings_id);
        settings.exists()
    }
}
```

### 7. Check Lifecycle

In each game interaction ensure that the following lifecycle check is made

```cairo
use tournaments::components::libs::lifecycle::{
    LifecycleAssertionsImpl, LifecycleAssertionsTrait
};

let token_metadata: TokenMetadata = world.read_model(game_id);
token_metadata.lifecycle.assert_is_playable(game_id, get_block_timestamp());
```

By following these steps, your game will be fully compatible with [Budokan](/budokan) and any other application using the Embeddable Game Standard.


## Embeddable Game Standard: Settings

Settings are a core feature of the Embeddable Game Standard (EGS), enabling games to be highly customizable and composable. By associating a game instance with a specific set of settings, you can create unique game modes, difficulty levels, or event rules—all onchain and provable.

### Why Use Settings?

* **Custom Game Modes:** Offer players or tournament organizers the ability to define special rules, deck sizes, or win conditions.
* **Composability:** Settings can be reused across games, quests, or tournaments, making it easy to launch new experiences.
* **Transparency:** All settings are stored onchain, so anyone can verify the rules for a given game instance.

> **Tip:** Use settings to power seasonal events, speedruns, or community challenges—just stamp a new settings profile and share the ID!

### How Settings Work in EGS

Each game instance can be linked to a settings profile via a unique `settings_id`. The settings metadata is stored onchain and can be queried or updated as needed.

#### Storing Settings Metadata

Within the EGS component, the `SettingsDetails` model is used to store metadata for each settings profile. Here's how you can set or update a settings profile:

```cairo
fn set_settings(
    ref self: ComponentState<TContractState>,
    settings_id: u32,
    name: felt252,
    description: ByteArray,
) {
    let mut world = WorldTrait::storage(
        self.get_contract().world_dispatcher(), @self.namespace.read(),
    );
    let mut store: Store = StoreTrait::new(world);
    store
        .set_settings_details(
            @SettingsDetails { id: settings_id, name, description, exists: true },
        );
}
```

* `settings_id`: Unique identifier for the settings profile.
* `name`: Human-readable name for the settings.
* `description`: Description or metadata for the settings profile.

> **Info:** The `SettingsDetails` model can be extended to include more fields (e.g., difficulty, allowed cards, etc.) depending on your game's needs.

### Creating Settings in Your Game

Within the Game contract, you will store the settings for a particular id in the model you defined as `settings_model` on [initialization](/embeddable-game-standard/implementation#5-implement-initialization-logic). Here's how you can set or update a settings profile:

### Best Practices & Next Steps

* Use clear names and descriptions for each settings profile.
* Store all relevant game rules in the settings metadata for transparency.
* Encourage your community to create and share custom settings for new challenges.
* For more on minting and using settings, see [Embedding Games](/embeddable-game-standard/implementation/embedding-games) and [Key Functions](/embeddable-game-standard/key-functions).

If you have questions or want to see more examples, check the rest of the EGS docs or reach out to the community!


## Dark Shuffle: FAQ

Find answers to the most common questions about Dark Shuffle. If you have a question not covered here, check the relevant guide section or reach out via the app's support channels.

### General

**What is Dark Shuffle?**

Dark Shuffle is a fully onchain deck-building roguelike game where you draft cards, battle monsters, and navigate a branching map—all powered by smart contracts for fairness and transparency.

**Do I need a wallet to play?**

Yes, you'll need a compatible wallet to play. See the [Onboarding Guide](/darkshuffle/guide/onboarding) for setup instructions.

**Is Dark Shuffle free to play?**

Yes! You can start and play games for free. Some [Budokan](/budokan) tournaments or special events may have entry requirements.

### Gameplay & Progression

**How do I start a new game?**

Go to the main menu and select "Start Game." You'll be guided through onboarding if it's your first time. See [Onboarding](/darkshuffle/guide/onboarding).

**What happens if I lose all my health?**

Your run ends and you'll need to start a new game. Try a different strategy or deck next time!

**Can I play multiple games at once?**

Yes, you can have multiple active games, each tracked separately.

### Drafting & Cards

**How does the draft phase work?**

You'll be presented with random card options each round. Pick one per round until your deck is complete. See the [Draft Guide](/darkshuffle/guide/draft).

**What do card rarities mean?**

Rarer cards are more powerful but appear less often in drafts. See [Cards Guide](/darkshuffle/guide/cards) for details.

**What are card effects?**

Cards can have effects that trigger on play, attack, or death. Combining effects can create powerful combos. More in the [Cards Guide](/darkshuffle/guide/cards).

### Battles

**How do battles work?**

Drag cards from your hand to the battlefield to attack the beast. Use your energy wisely and plan for card effects. See the [Battle Guide](/darkshuffle/guide/battle).

**What happens when a card dies?**

It's removed from your deck for the rest of the run. Some cards have death effects that trigger when destroyed.

**How do I win a battle?**

Defeat the beast before your hero's health drops to zero. Winning grants rewards and lets you progress on the map.

### Map & Nodes

**How is the map generated?**

Maps are randomly generated using secure onchain randomness. Each level has branching paths and different node types. See the [Map Guide](/darkshuffle/guide/map).

**What are nodes?**

Nodes are the beast encounters you see on the the map, each with connecting branches. Your choices affect the difficulty and rewards.

### Settings & Customization

**Can I customize the game rules?**

Yes! Use the settings menu to create or select custom game modes, draft rules, and more. See the [Settings Guide](/darkshuffle/settings).

**What is Auto-Draft mode?**

Auto-Draft skips the manual draft phase and gives you a pre-built deck. Great for quick games or special events.

### Tournaments & Competitions

**How do I join a tournament?**

Tournaments are hosted on [Budokan](/budokan), the permissionless tournament platform. There is a link to Budokan tournaments on the home page. See the [Enter Tournaments](/budokan/guide/enter) section on how to enter.

**Are there prizes?**

Yes! Many [Budokan](/budokan) tournaments offer prizes for top players. Details are listed in each event.

***

If you have more questions, explore the rest of the [Dark Shuffle Guide](/darkshuffle/guide/index) or contact support through the app.


import { ContractTable } from '../../components/ContractTable'
import { Button } from 'vocs/components'

![Overview](docs/ds-banner.png)

## Dark Shuffle

Dark Shuffle is a turn-based, collectible card game. Build your deck, battle monsters, and explore a procedurally generated world.

<Button href="https://darkshuffle.io" target="_blank" className="bg-white text-black" size="lg">
  Play
</Button>

### Table of Contents

* [Key Functions](/darkshuffle/key-functions)
* [Guide](/darkshuffle/guide)
* [Settings](/darkshuffle/settings)
* [FAQ](/darkshuffle/faq)

### Contracts

<ContractTable
  contracts={[[
  { name: "Game", address: "0xbcb2386436161d8d3afea0a805a8610ab90af5cf5582d866b83e9cb779bef3" },
  { name: "Game", address: "0x1e1c477f2ef896fd638b50caa31e3aa8f504d5c6cb3c09c99cd0b72523f07f7" }
],
[
  { name: "Battle", address: "0xbcb2386436161d8d3afea0a805a8610ab90af5cf5582d866b83e9cb779bef3" },
  { name: "Battle", address: "0x3befa9c969bf82bbfa0a96374da9f7aab172101298c0ff2611ec8c2fd02692" }
],
[
  { name: "Config", address: "0xbcb2386436161d8d3afea0a805a8610ab90af5cf5582d866b83e9cb779bef3" },
  { name: "Config", address: "0x66744a5847c4459e019511f390ba8a8da53c5d25de8cd4e24e5f3e450c5d038" }
]]}
/>


## Dark Shuffle: Key Functions

This section details the primary functions exposed by the Dark Shuffle game system. Each function is designed to be permissionless, composable, and secure.

### Game System (`contracts/src/systems/game/contracts.cairo`)

#### `start_game`

```cairo
fn start_game(ref self: T, game_id: u64);
```

**Purpose:** Initializes a new game instance for a player, setting up the draft or auto-drafting cards, and emits a game creation event.

**Parameters:**

* `game_id`: The unique identifier for the game.

***

#### `pick_card`

```cairo
fn pick_card(ref self: T, game_id: u64, option_id: u8);
```

**Purpose:** Allows the player to pick a card during the draft phase. Updates the draft and game state.

**Parameters:**

* `game_id`: The game instance.
* `option_id`: The index of the card option to pick.

***

#### `generate_tree`

```cairo
fn generate_tree(ref self: T, game_id: u64);
```

**Purpose:** Generates a new map/tree for the current game level, advancing the game to the next map phase.

**Parameters:**

* `game_id`: The game instance.

***

#### `select_node`

```cairo
fn select_node(ref self: T, game_id: u64, node_id: u8);
```

**Purpose:** Selects a node on the map, which typically starts a new battle with a monster.

**Parameters:**

* `game_id`: The game instance.
* `node_id`: The node to select.

***

#### `player_name`

```cairo
fn player_name(self: @T, game_id: u64) -> felt252;
```

**Purpose:** Returns the player's name for a given game.

***

#### `health`

```cairo
fn health(self: @T, game_id: u64) -> u8;
```

**Purpose:** Returns the hero's current health.

***

#### `game_state`

```cairo
fn game_state(self: @T, game_id: u64) -> GameState;
```

**Purpose:** Returns the current state of the game (Draft, Battle, Map, Over).

***

#### `xp`

```cairo
fn xp(self: @T, game_id: u64) -> u16;
```

**Purpose:** Returns the hero's experience points.

***

#### `cards`

```cairo
fn cards(self: @T, game_id: u64) -> Span<felt252>;
```

**Purpose:** Returns the names of the cards in the player's deck.

***

#### `monsters_slain`

```cairo
fn monsters_slain(self: @T, game_id: u64) -> u16;
```

**Purpose:** Returns the number of monsters defeated in the game.

***

#### `level`

```cairo
fn level(self: @T, game_id: u64) -> u8;
```

**Purpose:** Returns the current map level.

***

#### `map_depth`

```cairo
fn map_depth(self: @T, game_id: u64) -> u8;
```

**Purpose:** Returns the current depth in the map.

***

#### `last_node_id`

```cairo
fn last_node_id(self: @T, game_id: u64) -> u8;
```

**Purpose:** Returns the last selected node on the map.

***

#### `action_count`

```cairo
fn action_count(self: @T, game_id: u64) -> u16;
```

**Purpose:** Returns the number of actions taken in the game.

### Battle System (`contracts/src/systems/battle/contracts.cairo`)

#### `battle_actions`

```cairo
fn battle_actions(ref self: T, game_id: u64, battle_id: u16, actions: Span<Span<u8>>);
```

**Purpose:** Executes a sequence of battle actions (play cards, attack, end turn) for a given battle. Handles all game logic for a turn, including card effects, monster actions, and state updates.

**Parameters:**

* `game_id`: The game instance.
* `battle_id`: The battle instance.
* `actions`: A sequence of encoded actions (e.g., play card, attack, end turn).

### Config System (`contracts/src/systems/config/contracts.cairo`)

#### `add_settings`

```cairo
fn add_settings(
    ref self: T,
    name: felt252,
    description: ByteArray,
    starting_health: u8,
    start_energy: u8,
    start_hand_size: u8,
    draft_size: u8,
    max_energy: u8,
    max_hand_size: u8,
    draw_amount: u8,
    card_ids: Span<u64>,
    card_rarity_weights: CardRarityWeights,
    auto_draft: bool,
    persistent_health: bool,
    possible_branches: u8,
    level_depth: u8,
    enemy_attack_min: u8,
    enemy_attack_max: u8,
    enemy_health_min: u8,
    enemy_health_max: u8,
    enemy_attack_scaling: u8,
    enemy_health_scaling: u8,
) -> u32;
```

**Purpose:** Adds a new game settings profile, which defines the rules and parameters for a game instance.

***

#### `add_random_settings`

```cairo
fn add_random_settings(ref self: T) -> u32;
```

**Purpose:** Adds a new game settings profile with randomized parameters.

***

#### `add_creature_card`

```cairo
fn add_creature_card(ref self: T, name: felt252, rarity: u8, cost: u8, attack: u8, health: u8, card_type: u8, play_effect: CardEffect, attack_effect: CardEffect, death_effect: CardEffect);
```

**Purpose:** Adds a new creature card to the card pool.

***

#### `add_spell_card`

```cairo
fn add_spell_card(ref self: T, name: felt252, rarity: u8, cost: u8, card_type: u8, effect: CardEffect, extra_effect: CardEffect);
```

**Purpose:** Adds a new spell card to the card pool.

***

#### `setting_details`

```cairo
fn setting_details(self: @T, settings_id: u32) -> GameSettings;
```

**Purpose:** Returns the details of a game settings profile.

***

#### `settings_exists`

```cairo
fn settings_exists(self: @T, settings_id: u32) -> bool;
```

**Purpose:** Checks if a settings profile exists.

***

#### `game_settings`

```cairo
fn game_settings(self: @T, game_id: u64) -> GameSettings;
```

**Purpose:** Returns the game settings for a given game instance.

### Additional Utility Functions

* **Draft/Deck Management:**
  * `get_weighted_draft_list`, `get_draft_options`, `auto_draft` (see `utils/draft.cairo`): Used for generating draft options and decks.
* **Battle/Board Management:**
  * `attack_monster`, `remove_hand_card`, `draw_cards`, etc. (see `utils/board.cairo`, `utils/hand.cairo`): Used for in-battle logic and card management.
* **Map/Node Management:**
  * `node_available`, `get_monster_node`, `start_battle` (see `utils/map.cairo`): Used for map navigation and starting battles.

### Data Models

* **Game:** Tracks the state, health, XP, monsters slain, map progress, and actions.
* **Battle:** Tracks the current battle, hero/monster stats, and effects.
* **Draft:** Tracks the draft phase, available options, and selected cards.
* **GameSettings:** Defines the rules for a game instance (health, energy, deck size, etc.).


## Settings

Settings are one of the most powerful features of Dark Shuffle. They let you customize nearly every aspect of the game—deck size, draft rules, battle mechanics, map structure, and more. This flexibility is made possible by the [Embeddable Game Standard (EGS)](/embeddable-game-standard), allowing anyone to create, share, and use custom settings for new game modes, tournaments, and quests.

<div className="flex flex-row gap-6 items-start" style={{ margin: '2rem 0' }}>
  <div className="flex-1">
    <p>
      The settings viewer lets you browse and select from available settings profiles. Each profile can dramatically change how the game is played, from deck size to map structure.
    </p>
  </div>

  <div style={{ flexShrink: 0, minWidth: 220, maxWidth: 320 }}>
    <img src="/docs/darkshuffle/play-settings.png" alt="Settings Viewer" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

    <br />

    <em style={{ display: 'block', textAlign: 'center' }}>Figure 1: Settings viewer in Dark Shuffle.</em>
  </div>
</div>

### What Can You Configure?

Settings are grouped into four main categories:

| Category   | What You Can Change                                    |
| ---------- | ------------------------------------------------------ |
| **Game**   | Player health, energy, hand size, deck size, and more. |
| **Battle** | Enemy stats, energy scaling, effect triggers, etc.     |
| **Draft**  | Number of picks, rarity weights, auto-draft mode, etc. |
| **Map**    | Map depth, branching, node types, and progression.     |

> **Tip:** Custom settings let you create unique challenges, speedruns, or even entirely new game modes!

### Creating a Setting

<div className="flex flex-row gap-6 items-start" style={{ margin: '2rem 0' }}>
  <div className="flex-1">
    <ol>
      <li>Open the settings menu and select <strong>Create New Setting</strong>.</li>
      <li>Choose which parameters to customize (game, battle, draft, map).</li>
      <li>Save and name your setting—it's now available for you and others to use!</li>
    </ol>

    <p><strong>Info:</strong> All settings are stored on-chain, making them permissionless and composable. Anyone can use your setting for their own games or tournaments.</p>
  </div>

  <div style={{ flexShrink: 0, minWidth: 220, maxWidth: 320 }}>
    <img src="/docs/darkshuffle/create-settings.png" alt="Create Settings" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

    <br />

    <em style={{ display: 'block', textAlign: 'center' }}>Figure 2: Creating a new setting.</em>
  </div>
</div>

### Applying Settings: Real-World Examples

Custom settings unlock a huge variety of applications:

#### Unique Tournaments

Any setting can be used by [Budokan](/budokan/guide/submission) to create a competitive structure. For example, you can design a tournament with special draft rules, unique battle mechanics, or custom rewards.

#### Eternum Quests

Dark Shuffle debuted in Eternum Season 1, where a specific set of settings created fast and varied experiences for players. One key setting was <strong>Auto-Draft mode</strong>, which skips the draft phase and drops players straight into battle—perfect for quick games and cross-game events.

<div className="flex flex-row gap-6 items-start" style={{ margin: '2rem 0' }}>
  <div style={{ flex: 1, minWidth: 180, maxWidth: 320 }}>
    <img src="/docs/darkshuffle/settings-view-1.png" alt="Settings Example 1" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

    <br />

    <em style={{ display: 'block', textAlign: 'center' }}>Figure 3: Example custom settings in action.</em>
  </div>

  <div style={{ flex: 1, minWidth: 180, maxWidth: 320 }}>
    <img src="/docs/darkshuffle/settings-view-2.png" alt="Settings Example 2" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

    <br />

    <em style={{ display: 'block', textAlign: 'center' }}>Figure 4: Another custom settings view.</em>
  </div>
</div>

### Advanced: On-Chain Settings & Contract Functions

Settings are managed by smart contracts, making them transparent and tamper-proof. Key contract functions include:

* [`add_settings`](/darkshuffle/key-functions#add_settings): Create a new settings profile.
* [`setting_details`](/darkshuffle/key-functions#setting_details): View the details of a setting.
* [`game_settings`](/darkshuffle/key-functions#game_settings): See which settings are applied to a game.

> **Info:** Developers and advanced users can use these functions to automate tournaments, create new game types, or integrate with other on-chain games.

***

### Related Guides

* [Draft Guide](/darkshuffle/guide/draft): How settings affect the draft phase
* [Battle Guide](/darkshuffle/guide/battle): How settings change battle mechanics
* [Key Functions](/darkshuffle/key-functions): Technical reference for all contract functions
* [Budokan Tournaments](/budokan/guide/submission): Using settings for competitive play

If you have questions or want to share your custom settings, join the community or reach out via the app's support channels!


## Battle

Battles are the heart of Dark Shuffle—where your drafted deck, strategy, and luck are put to the test against powerful beasts. Winning battles earns you rewards and brings you closer to victory, while defeat can end your run!

### Battle Screen Layout

<div style={{ maxWidth: '900px', margin: '2rem auto' }}>
  <img src="/docs/darkshuffle/battle.png" alt="Battle Screen" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

  <br />

  <em style={{ display: 'block', textAlign: 'center' }}>Figure 1: Battle screen layout.</em>
</div>

| Area                                      | Description                                                             |
| ----------------------------------------- | ----------------------------------------------------------------------- |
| **Reset Turn (Top Left)**                 | Button to reset your current turn and try a different play sequence.    |
| **Beast Opponent (Top Center)**           | The beast you're battling. Hover to see its effects and stats.          |
| **Battle Field (Center)**                 | Place your cards here to attack the beast.                              |
| **End Turn Button (Right)**               | Ends your turn and simulates the battle phase.                          |
| **Current Effect Rewards (Bottom Left)**  | Shows rewards earned for triggering certain effects or type advantages. |
| **Player Area (Bottom Center)**           | Displays your hero (energy, health) and your current hand of cards.     |
| **Remaining Card Counter (Bottom Right)** | Shows how many cards are left in your deck.                             |

### How a Turn Works

At the start of each turn:

* Your hero's energy is refilled to the current max.
* You draw cards up to your hand size (both are set by the [game settings](/darkshuffle/settings)).
* You can play cards by dragging them to the battlefield, spending energy and triggering any play effects.

> **Tip:** Some cards have effects that trigger on play, attack, or death. Hover over a card to see its attributes
> and synergize your hand for maximum impact.

<div style={{ maxWidth: '700px', margin: '2rem auto' }}>
  <img src="/docs/darkshuffle/playing-card.png" alt="Playing Card" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

  <br />

  <em style={{ display: 'block', textAlign: 'center' }}>Figure 2: Dragging a card to the battlefield.</em>
</div>

* When a card's health drops to zero, it dies and is removed from your deck (death effects may trigger).
* You can reset your turn at any time before ending it.

### Ending Your Turn

When you're satisfied with your plays, press **End Turn** to simulate the battle:

* The beast and your cards exchange attacks.
* Effects (play, attack, death) are resolved.
* Your hero's energy is increased by 1 for the next turn.
* Cards are drawn from your deck according to the game settings.

<div style={{ maxWidth: '900px', margin: '2rem auto' }}>
  <img src="/docs/darkshuffle/beast-death.png" alt="Beast Defeated" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

  <br />

  <em style={{ display: 'block', textAlign: 'center' }}>Figure 3: Card defeated at end of turn.</em>
</div>

### End of Battle

A battle ends when:

* The beast is defeated (you win!), or
* Your hero's health drops to zero (game over).

If you win:

* You earn rewards (shown bottom left and on the map).
* Progress to the next map node or battle.

<div style={{ maxWidth: '700px', margin: '2rem auto' }}>
  <img src="/docs/darkshuffle/reward.png" alt="Reward Display" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

  <br />

  <em style={{ display: 'block', textAlign: 'center' }}>Figure 4: Rewards earned after a battle.</em>
</div>

> **Info:** All battle actions and outcomes are managed by smart contracts, ensuring fairness and transparency. For technical details, see the [Key Functions](/darkshuffle/key-functions#battle_actions) reference.

***

If you want to master battles, experiment with different decks and strategies, and check the [Cards Guide](/darkshuffle/guide/cards) for effect and synergy ideas!


## Cards

Cards are the core of your strategy in Dark Shuffle. Each card brings unique abilities, stats, and synergies to your deck. Understanding card attributes, rarities, and types is key to building a winning deck and outsmarting your opponents.

### Card Anatomy

Each card displays several important attributes:

<div style={{ maxWidth: '700px', margin: '2rem auto' }}>
  <img src="/docs/darkshuffle/typhon-card.png" alt="Typhon Card Example" style={{ width: '50%', display: 'block', margin: '0 auto' }} />

  <br />

  <em style={{ display: 'block', textAlign: 'center' }}>Figure: Example card layout (Typhon).</em>
</div>

| Attribute   | Location      | Description                                                                                 |
| ----------- | ------------- | ------------------------------------------------------------------------------------------- |
| **Energy**  | Top Left      | Energy required to play the card.                                                           |
| **Rarity**  | Top Right     | How rare the card is ([see Rarities](#rarities)).                                           |
| **Effects** | Center        | Special abilities, triggered by play, attack, or death ([see Card Effects](#card-effects)). |
| **Attack**  | Bottom Left   | The card's attack strength.                                                                 |
| **Type**    | Bottom Center | Card's type, which determines strengths/weaknesses ([see Types](#types)).                   |
| **Health**  | Bottom Right  | The card's health value.                                                                    |

### Card Effects

Each card can have one or more effects, which activate at different times:

* **Play:** Triggers as soon as the card is played.
* **Attack:** Triggers when the card attacks a beast; stat increases are compounded.
* **Death:** Triggers when the card is destroyed.

> **Tip:** Combining cards with synergistic effects can create powerful combos and turn the tide of battle!

### Rarities

Rarity affects how often a card appears in drafts and its overall power level:

| Rarity    | Description               |
| --------- | ------------------------- |
| Common    | Most frequently seen.     |
| Uncommon  | Less frequent, stronger.  |
| Rare      | Powerful, appears rarely. |
| Epic      | Very strong, very rare.   |
| Legendary | The rarest and strongest. |

> **Info:** Rarer cards are more powerful, but you'll see them less often during the draft.

### Types

Card types determine strengths and weaknesses in battle:

| Type    | Strong Against | Weak Against |
| ------- | -------------- | ------------ |
| Magical | Brute          | Hunter       |
| Brute   | Hunter         | Magical      |
| Hunter  | Magical        | Brute        |
| Spell   | —              | —            |

> **Tip:** Plan your deck and map route based on the types you draft. Check beast types and effects before choosing your path!

***

If you want to see all available cards, check the in-game card browser or the [Draft Guide](/darkshuffle/guide/draft) for tips on building your deck.


## Draft Phase: Building Your Deck

The draft phase is the first step in every Dark Shuffle game (unless Auto-Draft is enabled in your [Settings](/darkshuffle/settings)). Here, you select cards from randomly generated options to build your deck—the foundation for your strategy throughout the game.

### How Draft Works (Player Experience)

During the draft, you'll be presented with several card options each round. Pick one card per round to add to your deck. The process repeats until your deck is complete. Your choices shape your playstyle and chances in battle!

![Draft Page](/docs/darkshuffle/draft.png)

<em style={{ display: 'block', textAlign: 'center' }}>Figure: Drafting cards for your deck.</em>

> **Tip:** The cards you draft determine your deck for the entire game. Choose wisely—rarer cards are more powerful but less likely to appear!

### Draft Page Layout

* **Draft Options (center):** Where you pick from the current card choices.
* **Picks Analysis (bottom):** See stats like Draft Counter, Energy Chart, and Card Type Counter to help balance your deck.
* **Picks Display (right):** Shows cards you've already chosen. Hover for details.

### Rarity & Card Types

Cards are marked with rarity, which affects how often they appear. Rarer cards are generally stronger. For a full list of card types and rarities, see the [Cards Guide](/darkshuffle/guide/cards).

### How Draft Works On-Chain

The draft phase is powered by smart contracts, ensuring fairness and transparency. Here's what happens under the hood:

* **Game Start:**
  * The contract function [`start_game`](/darkshuffle/key-functions#start_game) initializes your game and sets up the draft (or auto-draft if enabled).
* **Drafting Cards:**
  * Each time you pick a card, the [`pick_card`](/darkshuffle/key-functions#pick_card) function updates your deck and the draft state.
  * The contract uses [VRF](https://docs.cartridge.gg/vrf/overview) to generate one set of selections ensuring options
    are fair and tamper-proof.
* **Deck Completion:**
  * Once all picks are made, your deck is locked in for the rest of the game.

> **Info:** All draft actions are recorded on-chain, making the process provable and tamper-proof. You can view the full list of game contract functions in the [Key Functions](/darkshuffle/key-functions) reference.

### Advanced: Custom Draft Settings

Game creators can define custom draft rules (deck size, rarity weights, etc.) using the [`add_settings`](/darkshuffle/key-functions#add_settings) contract function. This enables new game modes and experiments with deck-building mechanics.

### Next Steps & Related Guides

* [Cards Guide](/darkshuffle/guide/cards): Learn about card types and rarities
* [Battle Guide](/darkshuffle/guide/battle): See how your drafted deck is used in combat
* [Key Functions](/darkshuffle/key-functions): Technical reference for all game contract functions
* [Settings](/darkshuffle/settings): Enable Auto-Draft or customize your game experience

If you have questions or want to dive deeper into the contract logic, check the [Key Functions](/darkshuffle/key-functions) page or reach out via the app's support channels.


## Dark Shuffle: Guide

Welcome to the Dark Shuffle guide! Here you'll find everything you need to get started, master the mechanics, and discover advanced strategies for success. Whether you're a new player or looking to sharpen your skills, this guide covers every aspect of the game.

### Table of Contents

* [Onboarding](/darkshuffle/guide/onboarding): Setting up your wallet and starting your first game
* [Draft](/darkshuffle/guide/draft): Building your deck and understanding the draft phase
* [Cards](/darkshuffle/guide/cards): Card types, rarities, and effects
* [Battle](/darkshuffle/guide/battle): How battles work and tips for victory
* [Map](/darkshuffle/guide/map): Navigating the map and planning your route
* [Settings](/darkshuffle/settings): Customizing your game experience

### Overview

Dark Shuffle is a fully onchain deck-building roguelike where every decision matters. In this guide, you'll learn:

1. **How to onboard and set up your wallet** for seamless play.
2. **The core gameplay loop**—from drafting cards to battling monsters and navigating the map.
3. **How to build and optimize your deck** through the draft phase and card synergies.
4. **Battle mechanics and strategies** to defeat increasingly tough opponents.
5. **How to use custom settings** to create unique game modes and challenges.
6. **How to join tournaments and competitions** for rewards and glory.

Each section provides step-by-step instructions, visuals, and tips to help you become a Dark Shuffle master. Dive in and start your adventure!


## Map

Maps are randomly generated and split into levels, where each level contains various nodes and branches to choose from. The path you take through the map shapes your encounters, rewards, and overall strategy.

<div style={{ maxWidth: '700px', margin: '2rem auto' }}>
  <img src="/docs/darkshuffle/map.png" alt="Map" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

  <br />

  <em style={{ display: 'block', textAlign: 'center' }}>Figure 1: Example of a randomly generated map.</em>
</div>

### How Maps Work

* **Levels & Nodes:**\
  Each map is divided into levels. Every level contains several nodes (encounters), and you choose which node to visit next.

* **Branching Paths:**\
  Each node consists of multiple branches to choose from to following nodes. Your choices affect the difficulty, types of encounters, and potential rewards.

* **Progression:**\
  As you advance, the map gets more challenging, with tougher monsters and better rewards.

> **Tip:** Plan your route based on your deck's strengths and the types of nodes ahead. Some paths may offer healing, rare rewards, or easier battles.

### On-Chain Map Generation & Logic

The map system is powered by smart contracts to ensure fairness and unpredictability:

* **Random Generation:**\
  When you start a new game or advance to a new level, the contract uses secure randomness (via [VRF](https://docs.cartridge.gg/vrf/overview)) to generate the map layout and available nodes. This means no one—not even the game creators—can predict or manipulate your map.

* **Key Contract Functions:**
  * [`generate_tree`](/darkshuffle/key-functions#generate_tree): Generates a new map/tree for the current game level.
  * [`select_node`](/darkshuffle/key-functions#select_node): Lets you choose which node to visit next, triggering the appropriate encounter.

* **Node Types:**\
  The contract can generate different types of encounters based on the current level and your progress. The variety and frequency of nodes can be customized via [Settings](/darkshuffle/settings).

> **Info:** All map actions and choices are recorded on-chain, making your journey provable and tamper-proof. For technical details, see the [Key Functions](/darkshuffle/key-functions) reference.


## Getting Started: Onboarding

This guide will help you set up your [Controller](https://cartridge.gg/controller) and get ready to play Dark Shuffle.

### Setting Up Your Wallet

Follow these steps to get started:

1. If you don't already have a wallet, select Controller and sign up.
2. Choose your preferred login method. The Cartridge Controller supports:
   * Social logins (Discord)
   * Other blockchain wallets (Metamask, Phantom, Rabby)
   * Passkey
3. Complete the sign-up process as guided.
4. Once your wallet is set up, connect it to Budokan through the platform's wallet connection interface.

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>
      The Cartridge Controller offers extended features ideal for on-chain games, including signerless transactions and multi-platform login options.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/darkshuffle/controller-sign-up.png" alt="Budokan Wallets" width="400" height="200" />

    <br />

    <em>Figure 1: Controller sign up page.</em>
  </div>
</div>

> **Tip:** Using the Cartridge Controller enables gas-less transactions and a smoother experience across all supported games.

### Start A Game

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>
      Dark Shuffle offers a range of ways to play. On the home page buttons allow you to jump into a game,
      manage games you currently have or go to [Budokan](/budokan) to see DS tournaments.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/darkshuffle/actions.png" alt="Dark Shuffle Actions" width="400" height="200" />

    <br />

    <em>Figure 2: Dark Shuffle game actions.</em>
  </div>
</div>

#### Play Menu

This is where you can start your Dark Shuffle journey by selecting a setting and minting a free game to play! Each
game is associated with a particular setting, which is a permissionless evolution to expiriment with different
mechanics of the game. The default which is pre-selected is the base game.

#### My Games

All games of Dark Shuffle are themselves an NFT, so this menu keeps track of the games that you currently own.

* Games are marked with several different attributes:
  * Player Name (defaults to controller username)
  * Game stats (health, xp)
  * Setting
  * Expiration time
  * Whether they are a tournament game or free to play

<div className="flex flex-row gap-4 items-start">
  <div className="flex-shrink-0">
    <img src="/docs/darkshuffle/play-settings.png" alt="Dark Shuffle Play" width="400" height="200" />

    <br />

    <em>Figure 3: Play Menu.</em>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/darkshuffle/my-games.png" alt="Dark Shuffle Games" width="400" height="200" />

    <br />

    <em>Figure 2: My Games Menu.</em>
  </div>
</div>

### Next Steps & Related Guides

* [Draft](/darkshuffle/guide/draft)
* [Cards](/darkshuffle/guide/cards)
* [Battle](/darkshuffle/guide/battle)
* [Budokan Tournaments](/budokan/guide/submission)
* [FAQ](/darkshuffle/faq)

If you have questions or need help, check the FAQ or contact support through the app.


## Budokan: FAQ

Welcome to the Budokan FAQ! Here you'll find answers to the most common questions about using the Budokan tournament platform. If you can't find what you're looking for, check our other guides or contact support through the app.

### General

**What is Budokan?**

Budokan is a permissionless tournament platform for on-chain games, allowing anyone to create, join, and sponsor tournaments using Starknet wallets and a variety of supported tokens.

**Who can participate in Budokan tournaments?**

Anyone with a supported Starknet wallet who meets the tournament's entry requirements can participate.

### Getting Started & Wallets

**How do I get started on Budokan?**

See our [Onboarding Guide](/budokan/guide/onboarding) for step-by-step instructions on setting up your wallet and connecting to Budokan.

**Which wallets are supported?**

Budokan supports Cartridge Controller (recommended), Argent, Braavos, and more. See the [Onboarding Guide](/budokan/guide/onboarding) for details.

**Do I need a wallet to join a tournament?**

Yes, a Starknet wallet is required to enter tournaments, claim prizes, and interact with the platform.

### Tournaments & Entry

**How do I find and join a tournament?**

Browse tournaments on the overview page, select one to view details, and follow the steps in [Entering Tournaments](/budokan/guide/enter) to join.

**What are entry requirements?**

Entry requirements can include holding specific tokens/NFTs, qualifying in previous tournaments, or being on a whitelist. See [Entry Requirements](/budokan/guide/create/entry-requirements) for more info.

**Can I join multiple tournaments?**

Yes, you can join as many tournaments as you qualify for.

**What if I don't meet the entry requirements?**

Review the requirements section on the tournament page for guidance. You may need to acquire certain tokens or qualify in another event.

### Prizes & Fees

**How are prizes funded and distributed?**

Prizes can be funded by tournament creators, sponsors, or the community. They are distributed according to the rules and splits set for each tournament. See [Prizes](/budokan/guide/prizes) for details.

**What tokens can be used for entry fees and prizes?**

Currently, Budokan uses a whitelist of supported tokens. In the future, any token on Ekubo and NFTs will be supported. See [Entry Fees](/budokan/guide/create/entry-fees) and [Prizes](./guide/prizes).

**How do I claim my prize?**

After the tournament ends and results are verified, use the **Claim Prizes** button on the tournament page. See [Prizes](/budokan/guide/prizes) for step-by-step instructions.

**Can sponsors add prizes after a tournament has started?**

Yes! Sponsors and community members can add prizes at any time before the tournament ends. See [Prizes](/budokan/guide/prizes).

### Creating & Managing Tournaments

**How do I create a tournament?**

Click the **Create Tournament** button in the navigation and follow the steps in [Creating a Tournament](/budokan/guide/create).

**What customization options are available?**

You can set game, schedule, entry requirements, fees, prize structure, and more. See [Creating a Tournament](/budokan/guide/create) for a full walkthrough.

**Can I edit a tournament after creation?**

Some settings (like prizes) can be updated before the tournament ends, but core settings are locked after creation. Double-check all details before confirming.

### Troubleshooting & Support

**Why can't I enter a tournament?**

Check that you meet all entry requirements and have a supported wallet connected. If you still have issues, contact support.

**Why can't I claim my prize?**

Ensure the tournament has ended, results are finalized, and you are eligible. If problems persist, see [Prizes](/budokan/guide/prizes) or contact support.

**Where can I get more help?**

Check our guides or contact support through the app for further assistance.

### More Resources

* [Onboarding Guide](/budokan/guide/onboarding)
* [Entering Tournaments](/budokan/guide/enter)
* [Creating a Tournament](/budokan/guide/create)
* [Prizes](/budokan/guide/prizes)

If you have suggestions for this FAQ, let us know!


import { ContractTable } from '../../components/ContractTable'
import { Button } from 'vocs/components'

![Overview](/banner-1200x630.webp)

## Budokan

Budokan is an onchain tournament system designed to power competitive gaming experiences on Starknet. It provides a robust, modular, and extensible framework for:

* Creating and managing tournaments with flexible schedules and rules
* Supporting a variety of entry requirements and fee structures
* Handling prize pools and distribution (ERC20, ERC721, and custom tokens)
* Integrating with embeddable game standards for seamless game onboarding
* Leveraging Dojo world storage and event systems for composability and upgradability

<Button href="https://budokan.gg" target="_blank" className="bg-white text-black" size="lg">
  Launch App
</Button>

### Table of Contents

* [Key Functions](/budokan/key-functions)
* [Guide](/budokan/guide)
* [FAQ](/budokan/faq)

### Contracts

<ContractTable
  contracts={[[
  { name: "Budokan", address: "0xbcb2386436161d8d3afea0a805a8610ab90af5cf5582d866b83e9cb779bef3" },
  { name: "Budokan", address: "0x5accc0e54259cb3176450fa730fc5824cf2d3e550aec385cdaaa6250efdff27" }
]]}
/>

### Key Features

* **Modular Architecture**: Components for tournaments, games, schedules, and prizes can be extended or replaced.
* **Secure and Permissionless**: Anyone can create or enter tournaments, with robust checks for entry requirements and prize claims.
* **Flexible Entry and Prize Logic**: Supports entry fees, qualification proofs, and multiple prize types.
* **Leaderboard and Scoring**: Built-in leaderboard management and score submission.

### Use Cases

* Esports tournaments for onchain games
* Community competitions and challenges
* Automated prize distribution for game events
* Open standards for game developers to integrate with tournament infrastructure

Budokan is designed to be the backbone for provable, transparent, and fair onchain competitions, enabling new forms of player engagement and game design.


## Budokan: Key Functions

This section details the primary functions exposed by the Budokan tournament system. Each function is designed to be permissionless, composable, and secure.

### `create_tournament`

```cairo
fn create_tournament(
    ref self: TState,
    creator_rewards_address: ContractAddress,
    metadata: Metadata,
    schedule: Schedule,
    game_config: GameConfig,
    entry_fee: Option<EntryFee>,
    entry_requirement: Option<EntryRequirement>,
) -> TournamentModel;
```

**Purpose:** Create a new tournament with specified metadata, schedule, game configuration, entry fee, and requirements. Mints a game token to the creator for reward distribution.

**Parameters:**

* `creator_rewards_address`: Address to receive the creator's game token.
* `metadata`: Tournament metadata (name, description, etc.).
* `schedule`: Tournament schedule (registration, submission, finalization phases).
* `game_config`: Game configuration (game address, settings, prize spots).
* `entry_fee`: Optional entry fee (ERC20/721, amount, etc.).
* `entry_requirement`: Optional qualification requirement.

**Returns:** Tournament model struct.

***

### `enter_tournament`

```cairo
fn enter_tournament(
    ref self: TState,
    tournament_id: u64,
    player_name: felt252,
    player_address: ContractAddress,
    qualification: Option<QualificationProof>,
) -> (u64, u32);
```

**Purpose:** Register a player for a tournament, minting a game token and assigning an entry number.

**Parameters:**

* `tournament_id`: ID of the tournament to enter.
* `player_name`: Name of the player (felt252).
* `player_address`: Address to mint the game token to.
* `qualification`: Optional qualification proof.

**Returns:** Tuple of (game token ID, entry number).

***

### `submit_score`

```cairo
fn submit_score(
    ref self: TState,
    tournament_id: u64,
    token_id: u64,
    position: u8,
);
```

**Purpose:** Submit a score/position for a tournament entry. Updates the leaderboard and marks the score as submitted.

**Parameters:**

* `tournament_id`: ID of the tournament.
* `token_id`: Game token ID for the entry.
* `position`: Leaderboard position (1-based index).

***

### `claim_prize`

```cairo
fn claim_prize(
    ref self: TState,
    tournament_id: u64,
    prize_type: PrizeType,
);
```

**Purpose:** Claim a prize for a tournament after it is finalized. Handles entry fee and custom prize types.

**Parameters:**

* `tournament_id`: ID of the tournament.
* `prize_type`: Type of prize to claim (entry fees, custom, etc.).

***

### `add_prize`

```cairo
fn add_prize(
    ref self: TState,
    tournament_id: u64,
    token_address: ContractAddress,
    token_type: TokenType,
    position: u8,
) -> u64;
```

**Purpose:** Add a new prize to a tournament for a specific leaderboard position.

**Parameters:**

* `tournament_id`: ID of the tournament.
* `token_address`: Address of the prize token.
* `token_type`: Type of token (ERC20, ERC721, etc.).
* `position`: Leaderboard position for the prize.

**Returns:** Prize ID.

***

### `register_token`

```cairo
fn register_token(
    ref self: TState,
    address: ContractAddress,
    token_type: TokenType,
);
```

**Purpose:** Register a new token (ERC20/ERC721) for use in tournaments.

**Parameters:**

* `address`: Token contract address.
* `token_type`: Type of token.

***

### `get_leaderboard`

```cairo
fn get_leaderboard(
    self: @TState,
    tournament_id: u64,
) -> Array<u64>;
```

**Purpose:** Retrieve the current leaderboard for a tournament.

**Parameters:**

* `tournament_id`: ID of the tournament.

**Returns:** Array of game token IDs ordered by position.

***

### Additional Functions

* `total_tournaments`: Returns the total number of tournaments created.
* `tournament`: Returns the tournament model for a given ID.
* `get_registration`: Returns registration details for a game token.
* `get_prize`: Returns prize details for a given prize ID.
* `tournament_entries`: Returns the number of entries for a tournament.
* `is_token_registered`: Checks if a token is registered for tournaments.
* `current_phase`: Returns the current phase of a tournament.
* `get_tournament_id_for_token_id`: Returns the tournament ID for a given game token.


## Entering Tournaments

This guide will walk you through how to find, enter, and track tournaments. Whether you're a new or returning player, follow these steps to get started.

### Browsing Tournaments

On the **Overview** page, you can:

* Filter tournaments by game, status (upcoming, live, ended), or your participation.
* View summarized information on each tournament card, including:
  * Name
  * Duration
  * Number of participants
  * Time remaining
  * Entry fee (in $)
  * Prize pot (in $)
  * Key badges for important details (explained on the full details page)

![Overview](/docs/overview.png)
*Figure 1: Tournament overview page.*

### Viewing Tournament Details

To learn more about a tournament:

1. Click on a tournament card to open its details page.
2. Review the following sections:
   * **Requirements and Interactions** (top-right)
   * **Tournament Details**
   * **Timeline**
   * **Prizes**
   * **Scores (Entries)**
   * **My Entries**

The **Timeline** shows the tournament's structure, including the submission period after the tournament ends.

![Tournament Details](/docs/tournament-details.png)
*Figure 2: Tournament details page.*

> **Note:** Scores must be submitted during the submission period after the tournament ends to be eligible for prizes. The platform provides tools to handle this automatically, but you can also submit scores manually through the app.

### How to Enter a Tournament

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>To join a tournament:</p>

    <ol style={{ listStyleType: 'decimal', marginLeft: '1.5em' }}>
      <li>On the tournament details page, click the <strong>Enter Tournament</strong> button.</li>

      <li>
        <div>
          Review the entry fee breakdown, including:

          <ul style={{ listStyleType: 'disc', marginLeft: '1.5em' }}>
            <li>Tournament creator fees</li>
            <li>Game fees</li>
            <li>Prize pool contribution</li>
          </ul>
        </div>
      </li>

      <li>Check any entry requirements and confirm you qualify.</li>
      <li>Enter your player name when prompted.</li>
      <li>Confirm your entry and pay any required fees.</li>
    </ol>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/enter-tournament.png" alt="Entering a tournament" width="300" height="300" />

    <br />

    <em>Figure 3: Entering a tournament.</em>
  </div>
</div>

> **Tip:** If you do not meet the entry requirements, review the requirements section for guidance on how to qualify.

### After Entering

Once you have entered a tournament:

* Your entry will appear in the **Scores (Entries)** table.
* You will see your game listed under **My Entries**.
* Any entry fees you pay are instantly added to the prize pool.

![Entered Tournament](/docs/entered-tournament.png)
*Figure 4: After entering a tournament.*

### Related Guides

* [Submitting Scores](/budokan/guide/submission)
* [Tournament Prizes](/budokan/guide/prizes)

If you have questions or encounter issues, check the [FAQ](/budokan/faq) or contact support through the app.


## Budokan: Guide

This guide walks you through the complete process of using Budokan, from creating tournaments to claiming prizes.

### Table of Contents

* [Onboarding](/budokan/guide/onboarding)
* [Entering a Tournament](/budokan/guide/enter)
* [Creating a Tournament](/budokan/guide/create)
* [Prizes](/budokan/guide/prizes)

### Overview

Budokan provides a complete tournament management system with three main phases:

1. Player Registration and Participation
2. Tournament Creation and Setup
3. Prize Management and Distribution

Each section of this guide provides detailed instructions and examples for these key processes.


## Getting Started: Onboarding

Welcome to Budokan! This guide will help you set up your wallet and get ready to play on-chain games. Budokan supports a variety of Starknet wallets, with a special recommendation for the [Cartridge Controller](https://cartridge.gg/controller) due to its advanced features and signerless transactions.

### Choosing a Wallet

Budokan currently supports connection through several wallets. For the best experience, we recommend using the Cartridge Controller, which enables gas-less transactions and seamless gameplay on the platform.

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <ul>
      <li><strong>Cartridge Controller</strong> (recommended)</li>
      <li>Argent</li>
      <li>Braavos</li>
    </ul>

    <p>
      The Cartridge Controller offers extended features ideal for on-chain games, including signerless transactions and multi-platform login options.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/wallets.png" alt="Budokan Wallets" width="400" height="200" />

    <br />

    <em>Figure 1: Supported wallets on Budokan.</em>
  </div>
</div>

### Setting Up Your Wallet

Follow these steps to get started:

1. If you don't already have a wallet, select Controller and sign up.
2. Choose your preferred login method. The Cartridge Controller supports:
   * Social logins (Discord)
   * Other blockchain wallets (Metamask, Phantom, Rabby)
   * Passkey
3. Complete the sign-up process as guided.
4. Once your wallet is set up, connect it to Budokan through the platform's wallet connection interface.

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>
      The Cartridge Controller makes onboarding easy, allowing you to use familiar social accounts or other wallets. After setup, you'll be ready to join tournaments and play games on Budokan.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/controller-sign-up.png" alt="Controller Onboarding" width="200" height="100" />

    <br />

    <em>Figure 2: Signing up with the Cartridge Controller.</em>
  </div>
</div>

> **Tip:** Using the Cartridge Controller enables gas-less transactions and a smoother experience across all supported games.

### Next Steps & Related Guides

* [Entering Tournaments](/budokan/guide/enter)
* [Submitting Scores](/budokan/guide/submission)
* [FAQ](/budokan/faq)

If you have questions or need help, check the FAQ or contact support through the app.


## Budokan Prizes

Budokan features a flexible, permissionless prize system that allows anyone to add prizes to new or ongoing tournaments. This guide explains how prizes work, how to add and claim them, and best practices for both players and sponsors.

### Supported Prize Tokens

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>
      For security, Budokan currently uses a whitelist of tokens for prizes. In the future, any token supported on Ekubo, as well as NFTs (ERC721), will be available for use. This enables communities and sponsors to contribute a wide variety of rewards.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/prize-token-list.png" alt="Prize Tokens" width="300" height="600" />

    <br />

    <em>Figure 1: Supported ERC20s and NFTs for prizes.</em>
  </div>
</div>

### How to Add Prizes

Prizes can be added at multiple stages during a tournament's lifecycle:

1. **During Tournament Creation:**
   * Set up prize tokens and distribution when creating your tournament.
   * Choose from supported ERC20s or NFTs.

![Prizes](/docs/prizes.png)
*Figure 2: Tournament Prizes Form during creation.*

2. **After Tournament Creation:**
   * Add prizes at any time before the tournament ends.
   * Go to the tournament page and click the **Add Prizes** button.

![Add Prizes Button](/docs/add-prizes-button.png)
*Figure 3: Add Prizes on the tournament page.*

> **Tip:** Sponsors and community members can contribute prizes even after a tournament has started, increasing engagement and excitement.

### Prize Eligibility & Distribution

Prizes are distributed based on the tournament's rules and leaderboard positions. Here's how it works:

* **Eligibility:**
  * Players must meet all tournament requirements and achieve a winning position to be eligible for prizes.

* **Distribution:**
  * Prizes will be allocated to winners after the tournament concludes, the submission period ends and the prizes have been claimed.
  * The distribution follows the splits set by the tournament creator or sponsor.

> **Note:** Always check the tournament details for specific prize eligibility rules and distribution breakdowns.

### Claiming Prizes

1. **When to Claim:**
   * Prizes become claimable after the tournament ends and all results are verified.
   * You will be notified in the app or via your tournament dashboard.

2. **How to Claim:**
   * Go to the tournament page and look for the **Claim Prizes** button in the top right.
   * The will effectively distribute all prizes, game fees and creator fees in a single tx.

### For Sponsors & Community Contributors

Budokan encourages sponsors and community members to add prizes to tournaments. Here's how you can get involved:

* **Adding Prizes:**
  * Use the **Add Prizes** button on any tournament page to contribute tokens or NFTs.
  * Specify the prize type, amount, and any special eligibility requirements.

* **Visibility:**
  * Your contribution will be visible on the tournament page, and you will be credited as a sponsor.

> **Tip:** Adding prizes can boost tournament participation and promote your project or community.

### Related Guides

* [Creating a Tournament](/budokan/guide/create)
* [Entry Fees](/budokan/guide/create/entry-fees)
* [Entry Requirements](/budokan/guide/create/entry-requirements)
* [Onboarding](/budokan/guide/onboarding)
* [FAQ](/budokan/faq)

If you have questions or need help, check the FAQ or contact support through the app.


## Submitting Scores

Congratulations on achieving a high score! To ensure your results count and you remain eligible for prizes, you must submit your score to the contract during the designated submission period. This guide explains how and when to submit, how verification works, and how automation can help.

### Submission Period

After a tournament ends, there is a dedicated window—called the **submission period**—for players to submit their scores on-chain. The tournament creator sets this window (minimum 15 minutes). It is crucial to submit your score during this time; otherwise, you may not qualify for prizes or leaderboard positions.

> **Note:** If you miss the submission period, your score may not be recognized, and you could forfeit any prizes.

### How to Submit Your Score

1. When the tournament ends, check the tournament page for the submission window and instructions.
2. Submit your score through the app interface during the submission period.
3. Once your score is submitted and verified, a checkmark or "verified" mark will appear next to your name in the leaderboard.

<div className="flex flex-row gap-4 items-center">
  <div className="flex-1">
    <img src="/docs/submit-button.png" alt="Submission Dialog" width="700" height="700" />

    <br />

    <em>Figure 1: Submit Scores Button.</em>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/submission-dialog.png" alt="Submission Dialog" width="400" height="200" />

    <br />

    <em>Figure 2: Submission dialog for top scores.</em>
  </div>
</div>

### Score Verification

* Submitted scores are validated by the contract to ensure they qualify for their claimed positions.
* Only verified scores are eligible for prizes and final leaderboard placement.

![Submitted Scores](/docs/submitted-scores.jpeg)
*Figure 3: Submitted scores table with verified entries.*

### Automated Submission

Budokan provides an automated submission bot that detects when a tournament ends and schedules the top scores to be submitted on-chain. This helps ensure that scores are not missed due to user error or forgetfulness.

You can find the code and instructions for running your own submission bot here:

[Submission Bot Template](https://github.com/Provable-Games/budokan-submission-bot)

> **Tip:** Even with automation, always double-check that your score has been submitted and verified before the submission window closes.

***

### Related Guides

* [Entering Tournaments](/budokan/guide/enter)
* [Prizes](/budokan/guide/prizes)
* [FAQ](/budokan/faq)

If you have questions or need help, check the FAQ or contact support through the app.


## Best Practices

This guide covers recommended practices for creating successful tournaments on Budokan. Following these guidelines will help protect your prize pools, attract genuine participants, and ensure a smooth experience for everyone.

### Sybil Resistance

#### Always Charge Entry Fees for Open Tournaments

If your tournament is open to everyone and has no entry requirements (token gating, qualification, or whitelist), **always charge a small entry fee**. This is critical for protecting your prize pool.

**Why this matters:**

* Without barriers to entry, bots and farmers can create unlimited wallets and play an infinite number of games to exploit prize distributions
* Even a small fee (e.g., $0.10–$1.00) creates enough friction to make mass exploitation unprofitable
* The fee doesn't need to be large—just enough to make the cost of running many accounts exceed potential rewards

**Recommended approaches:**

| Tournament Type        | Recommendation                                               |
| ---------------------- | ------------------------------------------------------------ |
| Open + Prize Pool      | Charge entry fee (required)                                  |
| Open + No Prizes       | Entry fee optional                                           |
| Token Gated            | Entry fee optional (token requirement provides protection)   |
| Qualification Required | Entry fee optional (prior tournament provides protection)    |
| Whitelisted            | Entry fee optional (address restriction provides protection) |

> **Rule of thumb:** If anyone can join and there's money to win, require an entry fee.

#### Combine Multiple Protections

For high-value prize pools, consider layering protections:

* Entry fee + token gating
* Entry fee + qualification from a previous tournament
* Token gating + whitelist for invite-only events

### Submission Period

#### Set Realistic Deadlines

The submission period determines how long players have to submit their final scores after the tournament ends. If no scores are submitted before the deadline, **the prize pool will go to the tournament creator**.

**Recommendations:**

* Set submission periods of at least 24–48 hours for casual tournaments
* For competitive events, 1–7 days gives players flexibility across time zones
* Monitor your tournament as the deadline approaches

#### Use Auto-Submit Infrastructure

Budokan provides infrastructure to help monitor and auto-submit scores. Take advantage of this:

* Bookmark your tournament page
* Set calendar reminders for the submission deadline
* Consider enabling auto-submission if available

### Prize Distribution

#### Plan Your Winner Distribution

Before creating a tournament, decide how you want to distribute prizes:

* **Top-heavy:** Rewards the best players heavily (e.g., 70/20/10 split)
* **Flat:** Spreads rewards more evenly across winners
* **Participation-focused:** Smaller prizes for more positions

Consider your goals:

* Competitive prestige → top-heavy
* Community engagement → flatter distribution
* Encouraging new players → participation rewards

### Timing and Scheduling

#### Avoid Overlapping with Major Events

Check for other tournaments, game updates, or community events that might compete for attention. Timing your tournament well can significantly impact participation.

#### Consider Time Zones

If your community is global, consider:

* Longer tournament durations (days rather than hours)
* Start times that work for multiple regions
* Extended submission periods

### Communication

#### Write Clear Descriptions

Use the tournament description to communicate:

* Any special rules or expectations
* The theme or purpose of the tournament
* Links to community channels for questions

#### Announce Your Tournament

After creation, share your tournament:

* In relevant Discord channels
* On social media
* Through community newsletters

### Pre-Launch Checklist

Before confirming your tournament, verify:

* [ ] Entry requirements match your intended audience
* [ ] Entry fee is set (if tournament is open with prizes)
* [ ] Prize distribution percentages total 100%
* [ ] Start and end times are correct
* [ ] Submission period gives players enough time
* [ ] Game settings are configured correctly
* [ ] Description clearly explains the tournament

> **Remember:** Once created, some tournament settings cannot be changed. Double-check everything before confirming.

### Related Guides

* [Creating a Tournament](/budokan/guide/create)
* [Entry Fees](/budokan/guide/create/entry-fees)
* [Entry Requirements](/budokan/guide/create/entry-requirements)
* [FAQ](/budokan/faq)

If you have questions or need help, check the FAQ or contact support through the app.


## Entry Fees

Budokan allows you to set entry fees for your tournaments using any supported token on Starknet. This feature lets communities leverage their own ecosystem tokens as payment for games on the platform, adding flexibility and value.

### Supported Tokens

<div className="flex flex-row">
  <p>
    For security, Budokan currently uses a whitelist of tokens for tournament entry fees. In the future, any token supported on Ekubo will be available for use. Support for ERC721 (NFT) entry fees is also coming soon.
  </p>

  <div className="flex-shrink-0">
    <img src="/docs/erc20-tokens.png" alt="Entry Fee Tokens" width="300" height="600" />

    <em>Figure 1: Entry fee tokens currently supported.</em>
  </div>
</div>

### Customizing Entry Fee Distribution

The entry fee form offers flexible options for setting the price of entry and how fees are split among different parties. To make things simple, values are converted to USD where possible, so both players and creators can easily compare amounts—even if they're unfamiliar with the token.

![Entry Fees](/docs/entry-fees.png)
*Figure 2: Entry Fees Form.*

#### How Entry Fees Are Split

* **Creator Fee:**
  * The percentage of each entry fee that goes to the tournament creator. This is automatically distributed to the creator's account (`Entry #0`) when a player enters.

* **Game Fee:**
  * The percentage of each entry fee that goes to the game developer. The creator sets this percentage, though a minimum base fee may be enforced in the future. The game developer receives this cut via the account holding `Game #0`.

* **Player Distribution (Prize Pool):**
  * The remaining amount is added to the tournament's prize pool. The creator decides how the prize is split among winners, based on the leaderboard size. Use the slider to adjust distribution weights, or manually enter the splits (they must total 100%).

> **Tip:** Use familiar tokens for your audience to encourage participation. Double-check your fee splits before confirming, as they can't be changed after creation.

***

### Related Guides

* [Creating a Tournament](/budokan/guide/create)
* [Prize Structure](/budokan/guide/prizes)
* [Onboarding](/budokan/guide/onboarding)
* [FAQ](/budokan/faq)

If you have questions or need help, check the FAQ or contact support through the app.


## Entry Requirements

Entry requirements let you control who can join your tournament, adding exclusivity and enabling unique playing conditions. Use these features to target specific communities, create multi-stage events, or restrict access as needed.

### Token Gating

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>
      You can require participants to own specific NFTs or tokens to enter your tournament. This is a great way to host exclusive events for certain communities without manually tracking eligible accounts.<br /><br />
      Currently, Budokan uses a whitelist of supported tokens for gating, similar to entry fee tokens. In the future, all tokens will be supported.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/erc20-tokens.png" alt="Entry Requirement Tokens" width="300" height="600" />

    <br />

    <em>Figure 1: Gated tokens currently supported.</em>
  </div>
</div>

![Token Gating](/docs/entry-requirements-token.png)
*Figure 2: Token Entry Requirements Form.*

> **Tip:** Use token gating to reward loyal holders or run special events for your community.

### Tournament Qualification

Budokan allows you to chain tournaments together, unlocking advanced formats such as:

* Multi-round tournaments
* Multi-game tournaments
* Multi-game, multi-round tournaments

![Tournament Qualification](/docs/entry-requirements-tournament-2.png)
*Figure 3: Selecting participants of a previous tournament.*

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>
      By leveraging Starknet and Dojo interoperability, you can create tournament structures that were not possible before. For example, you can require players to qualify in one tournament before entering another, or combine results across multiple games.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/championship-tweet.png" alt="Dark Shuffle World Championship" width="300" height="600" />

    <br />

    <em>Figure 4: Dark Shuffle World Championship.</em>
  </div>
</div>

> **Note:** Chaining tournaments is a powerful way to build leagues, championships, or community-driven series.

### Whitelisting Addresses

You can also restrict tournament access by whitelisting specific wallet addresses. Only those on the list will be able to join.

![Whitelisting](/docs/entry-requirements-whitelist.png)
*Figure 5: Whitelisting addresses for tournament entry.*

> **Tip:** Use whitelisting for invitation-only events or to reward select players.

### Related Guides

* [Creating a Tournament](/budokan/guide/create)
* [Entry Fees](/budokan/guide/create/entry-fees)
* [Onboarding](/budokan/guide/onboarding)
* [FAQ](/budokan/faq)

If you have questions or need help, check the FAQ or contact support through the app.


## Game Settings

Budokan supports fully customizable game settings for all games that implement the [Embeddable Game Standard (EGS)](/embeddable-game-standard). This allows tournament creators to experiment with new game modes, tailor experiences for their communities, and offer a wide variety of play styles.

### Why Customize Game Settings?

Custom game settings let you:

* Create unique tournament experiences
* Enable or disable specific game features
* Adjust difficulty, rules, or other parameters
* Encourage new strategies and community engagement

> **Tip:** Experimenting with different settings can help you discover popular new game modes and keep your tournaments fresh.

***

### How to Select and Customize Settings

<div className="flex flex-row gap-4 items-start">
  <div className="flex-1">
    <p>
      When creating a tournament, you can choose to customize the game settings. These settings are displayed as key-value pairs, read directly from the game contract on-chain. Click <strong>Select Settings</strong> to open the customization dialog.
    </p>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/game-settings.png" alt="Game Settings" width="400" height="200" />

    <br />

    <em>Figure 1: Customizing Game Settings in Budokan.</em>
  </div>
</div>

***

### Creating and Using Custom Settings

* Settings can be created permissionlessly through the games themselves.
* Any custom settings you create will be displayed and available for play within Budokan.
* You can select from existing settings or define new ones for your tournament.

<div className="flex flex-row gap-4 items-start">
  <div className="flex-shrink-0">
    <img src="/docs/game-settings-modal.png" alt="Game Settings Modal" width="300" height="200" />

    <br />

    <em>Figure 2: Selecting Specific Settings.</em>
  </div>

  <div className="flex-shrink-0">
    <img src="/docs/view-settings.png" alt="Game Settings View" width="300" height="200" />

    <br />

    <em>Figure 3: Viewing a selected setting.</em>
  </div>
</div>

> **Note:** All custom settings are transparent and visible to players, ensuring a fair and open tournament environment.

***

### Related Guides

* [Creating a Tournament](/budokan/guide/create)
* [Prizes](/budokan/guide/prizes)
* [FAQ](/budokan/faq)

If you have questions or need help, check the FAQ or contact support through the app.


## Creating a Tournament

Budokan lets anyone create tournaments for any game that supports the [Emedabble Game Standard](/embeddable-game-standard/index) (EGS). This guide walks you through the process, highlights customization options, and shares best practices for a successful tournament.

### Prerequisites

* A Starknet wallet ([see Onboarding](../onboarding))
* Prize tokens (if you want to offer custom prizes)

### How to Create a Tournament

#### 1. Open the Create Tournament Page

* Click the **Create Tournament** button in the navigation menu.

![Create Tournament Button](/docs/navigation.png)
*Figure 1: Create Tournament Button.*

This opens the Create Tournament page, where you can configure all aspects of your tournament.

![Create Tournament Page](/docs/create-tournament.png)
*Figure 2: Create Tournament Page.*

***

#### 2. Configure Tournament Details

* Select the game
* Adjust game settings ([see Game Settings](../create/entry-requirements))
* Enter a name and description
* Set the leaderboard size (number of winners)

***

#### 3. Set the Tournament Schedule

* Choose start and end times
* Set the submission period
* Select registration type:
  * Open (anyone can join)
  * Fixed (limited registration)

![Tournament Schedule](/docs/schedule.png)
*Figure 3: Tournament Schedule Form.*

***

#### 4. (Optional) Configure Entry Requirements

* Set qualification requirements
* Limit the number of players

![Tournament Entry Requirements](/docs/entry-requirements-tournament.png)
*Figure 4: Entry Requirements Form.*

For more details, see [Entry Requirements](../create/entry-requirements).

***

#### 5. (Optional) Set Entry Fees

* Choose entry fee tokens
* Define fee distribution
  * Tournament Creator %
  * Game %
  * Winner distribution

![Entry Fees](/docs/entry-fees.png)
*Figure 5: Entry Fees Form.*

For more details, see [Entry Fees](../create/entry-fees).

***

#### 6. (Optional) Set Up Prize Structure

* Choose prize types (ERC20s, ERC721s)
* Define how prizes are distributed
* Set winner positions

![Prizes](/docs/prizes.png)
*Figure 6: Tournament Prizes Form.*

***

#### 7. Review and Confirm

After completing the form, you'll see a tournament confirmation page. Review all details and confirm before submitting the transaction. This is your chance to double-check the structure and any prizes.

<div className="flex flex-row">
  <p>
    Once you confirm, your tournament will be created and visible to other players. Make sure you are happy with all settings before finalizing.
  </p>

  <div className="flex-shrink-0">
    <img src="/docs/tournament-confirmation.png" alt="Tournament Confirmation" width="300" height="600" />

    <em>Figure 7: Tournament confirmation dialog.</em>
  </div>
</div>

### Best Practices

* **Sybil Resistance:**
  * Avoid making tournaments with open, free entry and a prize pool, as this can lead to abuse (multiple entries per wallet). Consider qualification requirements or entry fees to protect your tournament.

* **Submission Period:**
  * Always note the submission period. If no scores are submitted before the deadline, the prize pool will be forfeited.
  * Budokan provides infrastructure to help monitor and auto-submit, but it's wise to bookmark your tournament and set reminders.

> **Tip:** Double-check all tournament settings before confirming. Once created, some options cannot be changed.

### Related Guides

* [Onboarding](/budokan/guide/onboarding)
* [Entry Requirements](/budokan/guide/create/entry-requirements)
* [Entry Fees](/budokan/guide/create/entry-fees)
* [Submitting Scores](/budokan/guide/submission)
* [FAQ](/budokan/faq)

If you have questions or need help, check the FAQ or contact support through the app.