> For the complete documentation index, see [llms.txt](https://critters-quest-1.gitbook.io/critters-quest-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://critters-quest-1.gitbook.io/critters-quest-docs/critter-quest-guides.md).

# Critter Quest Guides

## Table of Contents

* [Getting Started](#getting-started)
* [Core Game Mechanics](#core-game-mechanics)
* [Resource System](#resource-system)
* [Tools & Equipment](#tools--equipment)
* [Crafting System](#crafting-system)
* [Item Identification System](#item-identification-system)
* [Town Building System](#town-building-system)
* [Advanced Features](#advanced-features)
* [Technical Information](#technical-information)
* [Getting Started Checklist](#getting-started-checklist)

## Getting Started

### Welcome to Critters Quest

Critters Quest is a blockchain-based resource gathering and town-building game where players deploy NFT critters to gather resources, craft tools, and build thriving towns. The game combines strategic resource management with competitive elements like looting and leaderboards.

### First Steps(Beta)

* **Create Account**: Connect using email through Privy authentication system
* **Wallet Creation**: A wallet will be automatically generated for you upon email verification
* **Acquire Critter**: Get your first critter NFT (beta allocation process)
* **Initial Resources**: Each critter starts with a different amount of locked $QUEST tokens
* **Town Placement**: Place your town strategically on the map
* **First Deployment**: Deploy your first critter to gather basic resources

### Basic Controls

* **Desktop**: WASD to move, Shift to run faster
* **Mobile**: Use joystick (customizable position in settings)
* **Camera**: Mouse/touch to pan and zoom
* **Interaction**: Click on buildings, resources, and UI elements

## Core Game Mechanics

### Quest Token Economy - CRITICAL UNDERSTANDING

**Two Types of Quest Tokens:**

#### 1. Locked Quest (On Critter)

* **Used for**: Critter actions (gathering, moving, leveling Critter up)
* **Location**: Stored individually on each critter NFT
* **Cannot be transferred** only spent
* **Used for**: All critter-specific activities

#### 2. Town Bank Quest

* **Used for**: Town upgrades, building construction, crafting
* **Location**: Stored in your town's bank building
* **Can be**: Deposited/withdrawn
* **Required for**: All town development

**Payment Rules:**

* **Critter actions** = Locked Quest from that specific critter
* **Town/crafting actions** = Town Bank Quest

### Resource System

#### Resource Node Mechanics

* **Health Points**: Each resource has specific HP (720K to 99M+)
* **Level Gating**: Town level determines which resource tiers you can see
  * Level 1 Town = Can see Tier 1 resources
  * Level 2 Town = Can see Tier 1-2 resources
  * Level 3 Town = Can see Tier 1-3 resources
* **Daily Movement**: Resources randomly spawn every 12 hours
* **Finite Uses**: Each node has limited gathering attempts
* **Competition**: Multiple players can gather from same node

#### Tool Requirements & Level Scaling

* **Tier 1 Tools**: Access to basic resource yields
* **Tier 3+ Tools**: Advanced feature unlocked - **Resource Level Control**
  * Set difficulty level on any resource node
  * Higher levels = increased yield + longer time
  * Choose optimal risk/reward ratio

## Resource System

### Forest Resources (Axe)

<table><thead><tr><th width="100" data-type="image"></th><th>Resource</th><th>Town Level</th><th>HP</th><th>Key Drops</th></tr></thead><tbody><tr><td><a href="/files/OwhYvrLPRVep8HxEhPfj">/files/OwhYvrLPRVep8HxEhPfj</a></td><td>Sapling</td><td>1</td><td>720K</td><td>Wood, Unknown Recipe</td></tr><tr><td><a href="/files/8QzjMloOGk0BW7Quh12Q">/files/8QzjMloOGk0BW7Quh12Q</a></td><td>Birch</td><td>2</td><td>1.7M</td><td>Wood, Tree Sap</td></tr><tr><td><a href="/files/kg52v3mloFYP7Ca2eML8">/files/kg52v3mloFYP7Ca2eML8</a></td><td>Pine</td><td>3</td><td>3M</td><td>Coal, Tree Sap, </td></tr><tr><td><a href="/files/J98rx7kHWuy89qwzmZ73">/files/J98rx7kHWuy89qwzmZ73</a></td><td>Oak</td><td>3</td><td>5.8M</td><td>Magical Spores</td></tr><tr><td><a href="/files/CFT5z4VZgGb8LV7BiMnx">/files/CFT5z4VZgGb8LV7BiMnx</a></td><td>Maple</td><td>4</td><td>8.3M</td><td>Wood Tree Sap</td></tr><tr><td><a href="/files/RtcCtqUq4VxzKGT0sm9H">/files/RtcCtqUq4VxzKGT0sm9H</a></td><td>Ironwood</td><td>4</td><td>13.1M</td><td>Wood, Iron Ore</td></tr><tr><td><a href="/files/yC7JCUtBfzVLKj1I9CUp">/files/yC7JCUtBfzVLKj1I9CUp</a></td><td>Ancient Oak</td><td>6</td><td>29.1M</td><td>Wood, Ancient Wood</td></tr><tr><td><a href="/files/cUlFrAXPGpZy6SBrZ9qL">/files/cUlFrAXPGpZy6SBrZ9qL</a></td><td>Shimmerwood</td><td>8</td><td>38.8M</td><td>Ancient Wood, Diamonds</td></tr><tr><td><a href="/files/61sc7Buet6WzaKbUI0zk">/files/61sc7Buet6WzaKbUI0zk</a></td><td>Elderwood</td><td>8</td><td>59.4M</td><td>Ancient Wood , Recipes</td></tr><tr><td><a href="/files/XKmiGFi5QGSfKmVHN8Jc">/files/XKmiGFi5QGSfKmVHN8Jc</a></td><td>Crystal Pine</td><td>9</td><td>71.2M</td><td>Ancient Wood, Gems</td></tr></tbody></table>

### Mining Resources(PickAxe)

<table><thead><tr><th width="100" data-type="image"></th><th>Resource</th><th>Town Level</th><th>HP</th><th>Key Drops</th></tr></thead><tbody><tr><td><a href="/files/UtFWpyp6Ru6Nj7LNpth1">/files/UtFWpyp6Ru6Nj7LNpth1</a></td><td>Basic Rock</td><td>1</td><td>720K</td><td>Stone</td></tr><tr><td><a href="/files/i2M8WZ2EpzZUWlmM2vvd">/files/i2M8WZ2EpzZUWlmM2vvd</a></td><td>Common Deposit</td><td>2</td><td>1.7M</td><td>Coal, Iron Ore</td></tr><tr><td><a href="/files/HnUzwgXhhlwDqHSiontx">/files/HnUzwgXhhlwDqHSiontx</a></td><td>Mineral Outcrop</td><td>3</td><td>4M</td><td>Iron Ore, Steel Ingots</td></tr><tr><td><a href="/files/RiIBc4DRbeeYeRKcfLtI">/files/RiIBc4DRbeeYeRKcfLtI</a></td><td>Rich Vein</td><td>4</td><td>7.8M</td><td>Iron Ore, Copper Ore</td></tr><tr><td><a href="/files/ENnxMP9AGzrpOmHEtaYO">/files/ENnxMP9AGzrpOmHEtaYO</a></td><td>Rare Formation</td><td>4</td><td>11.3M</td><td>Copper Ore, Iron Ore</td></tr><tr><td><a href="/files/onlGpQ6NvL5UOAhbuLHy">/files/onlGpQ6NvL5UOAhbuLHy</a></td><td>Precious Deposit</td><td>5</td><td>15.1M</td><td>Gold Ore, Gold Dust</td></tr><tr><td><a href="/files/uTBNijXkRnNiciuB6ZUZ">/files/uTBNijXkRnNiciuB6ZUZ</a></td><td>Exceptional Cluster</td><td>6</td><td>29.1M</td><td>Gold Ore, Diamonds</td></tr><tr><td><a href="/files/2t48UHPhGoK6oWmCbL23">/files/2t48UHPhGoK6oWmCbL23</a></td><td>Pristine Geode</td><td>7</td><td>38.8M</td><td>Emeralds, Ruby, Recipes</td></tr><tr><td><a href="/files/h7W2q3yh3KPoxNNPvhjJ">/files/h7W2q3yh3KPoxNNPvhjJ</a></td><td>Ancient Formation</td><td>8</td><td>59.4M</td><td>Crystal Fragments, Ancient Relics, sapphires</td></tr><tr><td><a href="/files/IS3yaqTZA6t6dIbrBYZZ">/files/IS3yaqTZA6t6dIbrBYZZ</a></td><td>Legendary Remnant</td><td>9</td><td>71.2M</td><td>Tech Fragments, Amethyst, Emeralds</td></tr></tbody></table>

### Digging Resources(Shovel)

<table><thead><tr><th width="100" data-type="image"></th><th>Resource</th><th>Town Level</th><th>HP</th><th>Key Drops</th></tr></thead><tbody><tr><td><a href="/files/wVxjTYdb4LVh5sEZmRsv">/files/wVxjTYdb4LVh5sEZmRsv</a></td><td>Loose Soil</td><td>1</td><td>1.7M</td><td>Clay, Recipes</td></tr><tr><td><a href="/files/IQBZ3qVgHI4awSrggfDv">/files/IQBZ3qVgHI4awSrggfDv</a></td><td>Herb Patch</td><td>2</td><td>3M</td><td>Clay, herbs</td></tr><tr><td><a href="/files/dOCa0DAb0hhqmUkdTxTE">/files/dOCa0DAb0hhqmUkdTxTE</a></td><td>Seep</td><td>4</td><td>7.5M</td><td>Water, sand</td></tr><tr><td><a href="/files/H3YCXovxusszGIFG41pi">/files/H3YCXovxusszGIFG41pi</a></td><td>Mushroom Circle</td><td>8</td><td>14.5M</td><td>Mushroom, Magical Spore</td></tr><tr><td><a href="/files/j1W0ms7c2c5nBkEc0inC">/files/j1W0ms7c2c5nBkEc0inC</a></td><td>Ancient Grove</td><td>10+</td><td>99.2M</td><td>Ancient Relics, Tech Fragments, Light Essence</td></tr><tr><td><a href="/files/J6uf8kmVL9O76JCeaA03">/files/J6uf8kmVL9O76JCeaA03</a></td><td>Gravel</td><td>1</td><td>1.5M</td><td>Stone, Coal</td></tr><tr><td><a href="/files/QNxQs4GAbrLMRlpT68Xq">/files/QNxQs4GAbrLMRlpT68Xq</a></td><td>Mineral Deposit</td><td>3</td><td>5.8M</td><td>Copper Ore,  Coal</td></tr><tr><td><a href="/files/uk10XnaKxV8HM0RtNF7F">/files/uk10XnaKxV8HM0RtNF7F</a></td><td>Bone Pile</td><td>4</td><td>8.5M</td><td>Bone, Diamond Fragments</td></tr><tr><td><a href="/files/rHoVKyzcg3xTDhuumnrq">/files/rHoVKyzcg3xTDhuumnrq</a></td><td>Crystal Soil</td><td>8</td><td>19.4M</td><td>Crystal Fragments, Gems</td></tr><tr><td><a href="/files/FYtCvG9UpKn6J505YAyI">/files/FYtCvG9UpKn6J505YAyI</a></td><td>Ancient Cache</td><td>10</td><td>71.2M</td><td>Ancient Relics, Gems</td></tr></tbody></table>

### Reward System

<figure><img src="/files/SFoz45nrrWXf3U6GIMj6" alt=""><figcaption></figcaption></figure>

* **Guaranteed Rewards (Yellow Border)**: 100% participation reward
* **Common Drops (Grey Border)**: 100% chance for basic materials
* **Uncommon Drops (Green Border)**: 50% chance for upgraded materials
* **Rare Drops (Light Blue Border)**: 5% chance for premium materials
* **Bonus Items (Pink/Red Border)**: 1% chance for special tools/recipes<br>

### First Completion Bonus

The first player to complete a resource node unlocks additional potential rewards for themselves. All other players receive only guaranteed participation rewards.

## Tools & Equipment

### Tool Tier System

<table><thead><tr><th>Tier</th><th>Tool Type</th><th width="157">Damage Range</th><th>Luck Range</th><th>Durability Range</th><th>Sockets</th></tr></thead><tbody><tr><td>1</td><td>Wood Tool</td><td>20-40</td><td>0%</td><td>172,800-259,200</td><td>0</td></tr><tr><td>3</td><td>Stone Tool</td><td>60-100</td><td>2.5-5%</td><td>345,600-518,400</td><td>0-1</td></tr><tr><td>5</td><td>Steel Tool</td><td>120-180</td><td>5-10%</td><td>604,800-777,600</td><td>0-1</td></tr><tr><td>7</td><td>Diamond Tool</td><td>200-300</td><td>7.5-15%</td><td>695,520-894,240</td><td>0-2</td></tr><tr><td>9</td><td>Emerald Tool</td><td>325-475</td><td>10-20%</td><td>869,400-1,117,800</td><td>1-2</td></tr><tr><td>11</td><td>Advanced Tools</td><td>500-700</td><td>12.5-25%</td><td>1,173,690-1,509,030</td><td>1-3</td></tr></tbody></table>

### Advanced Tool Features (Tier 3+)

* **Resource Level Control**: Set difficulty level on resource nodes
* **Yield Multiplier**: Higher levels increase resource yield
* **Time Trade-off**: Higher levels require longer gathering time
* **Socket System**: Higher tier tools have sockets for upgrades

## Crafting System

### The Muddy Anvil (Blacksmith)

#### Pickaxe Crafting (Mining Tools)

**Wood Pickaxe (Tier 1)**

* Materials: 5 Wood
* Cost: 250 $QUEST (Town Bank)
* Crafting Time: 1 hour
* Durability: 172,800-259,200
* Repair Cost: 1 $QUEST/1000 durability

**Stone Pickaxe (Tier 3)**

* Materials: 15 Stone, 5 Wood, 2 Clay, 5 Coal, 3 Refined Sap
* Cost: 1000 $QUEST (Town Bank)
* Crafting Time: 3 hours
* Durability: 345,600-518,400

**Steel Pickaxe (Tier 5)**

* Materials: 10 Wood, 10 Stone, 7 Coal, 5 Clay, 5 Refined Sap, 3 Steel Ingot, 3 Copper Ingot
* Cost: 1500 $QUEST (Town Bank)
* Crafting Time: 8 hours
* Durability: 604,800-777,600

**Diamond Pickaxe (Tier 7)**

* Materials: 25 Wood, 50 Stone, 15 Coal, 15 Clay, 20 Refined Sap, 1 Refined Diamond, 2 Steel Ingot, 5 Gold Solution, 5 Copper Ingot
* Cost: 5000 $QUEST (Town Bank)
* Crafting Time: 24 hours
* Durability: 2,592,000-3,456,000

**Emerald Pickaxe (Tier 9)**

* Materials: 50 Wood, 35 Stone, 25 Coal, 25 Clay, 15 Refined Sap, 3 Refined Emerald, 1 Polished Diamond, 2 Gold Ingot, 25 Copper Ingot
* Cost: 15000 $QUEST (Town Bank)
* Crafting Time: 48 hours
* Durability: 5,184,000-6,912,000

#### Axe Crafting (Tree Chopping)

Similar progression with materials optimized for wood gathering.\
\
**PickAxe Crafting (Mining)**\
Similar progression with materials optimized for rock gathering.

#### Shovel Crafting (Digging)

Similar progression with materials optimized for soil resources.

#### Smelting Operations

* **Copper Ore Smelting**: 2 Wood, 1 Stone, 6 Coal + 2 Copper Ore = 1 Copper Ingot (Processing: 4h, Cost: 100 $QUEST)
* **Iron Ore Smelting**: 3 Wood, 2 Stone, 8 Coal + 3 Iron Ore = 1 Iron Ingot (Processing: 3h, Cost: 100 $QUEST)
* **Steel Forging**: 4 Wood, 2 Stone, 10 Coal + 2 Iron Ingot, 3 Coal = 1 Steel Ingot (Processing: 5h, Cost: 200 $QUEST)
* **Gold Ore Smelting**: 5 Wood, 3 Stone, 12 Coal + 1 Gold Ore, 1 Copper Ingot = 1 Gold Ingot (Processing: 6h, Cost: 200 $QUEST)

## Item Identification System

### The Mystic Mirror (Oracle)

#### Identification Process

Unknown items and recipes can be identified through a tiered system that determines what quality recipes you can discover.

| Level | Time | Cost ($QUEST) | Materials Required                                                                                                                     | Recipe Tiers Available  |
| ----- | ---- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| 1     | 4h   | 50            | 5 Wood                                                                                                                                 | T1 only                 |
| 2     | 4h   | 100           | 5 Wood, 5 Clay                                                                                                                         | T1-T2 weighted chances  |
| 3     | 4h   | 150           | 10 Wood, 5 Clay, 5 Stone                                                                                                               | T1-T3 weighted chances  |
| 4     | 4h   | 200           | 15 Wood, 10 Clay, 5 Stone, 5 Tree Sap                                                                                                  | T1-T4 weighted chances  |
| 5     | 3h   | 250           | 15 Wood, 10 Clay, 5 Tree Sap, 10 Stone, 5 Iron Ore                                                                                     | T1-T5 weighted chances  |
| 6     | 3h   | 300           | 20 Wood, 15 Clay, 15 Tree Sap, 15 Stone, 5 Copper Ore, 5 Iron Ore                                                                      | T1-T6 weighted chances  |
| 7     | 3h   | 350           | 20 Wood, 20 Clay, 20 Tree Sap, 20 Stone, 5 Copper Ore, 10 Iron Ore, 5 Gold Ore                                                         | T1-T7 weighted chances  |
| 8     | 2h   | 400           | 25 Wood, 25 Clay, 25 Tree Sap, 25 Stone, 10 Copper Ore, 15 Iron Ore, 5 Gold Ore, 5 Ancient Wood                                        | T1-T8 weighted chances  |
| 9     | 2h   | 450           | 30 Wood, 30 Clay, 30 Tree Sap, 30 Stone, 15 Copper Ore, 20 Iron Ore, 10 Gold Ore, 5 Ancient Wood, 1 Crystal Fragment                   | T1-T9 weighted chances  |
| 10    | 1h   | 500           | 40 Wood, 40 Clay, 40 Tree Sap, 40 Stone, 20 Copper Ore, 30 Iron Ore, 15 Gold Ore, 10 Ancient Wood, 1 Crystal Fragment, 1 Tech Fragment | T1-T10 weighted chances |

Higher identification levels cost more materials but give access to better recipe tiers. All costs are paid from Town Bank Quest.

## Town Building System

### Core Buildings

**The Muddy Anvil (Blacksmith)**

* Purpose: Tool crafting, weapon creation, metal working
* Functions: Pickaxe/Axe/Shovel crafting, smelting operations
* Upgrade Levels: 1-10+ with increasing capabilities

**The Building Barrel**

* Purpose: Construction materials, building upgrades
* Functions: Advanced building component creation

**The Glistening Nexus (Jeweler)**

* Purpose: Gem cutting, jewelry creation, enchantments
* Functions: Processing rare materials into valuable items

**The Glowing COG (Ancient Tech Lab)**

* Purpose: Advanced technology, ancient relic processing
* Functions: Tech fragment utilization, energy cell creation

**The Mystic Mirror (Oracle - Item Identification)**

* Purpose: Unknown item identification, recipe discovery
* Functions: Converting unknown recipes into usable knowledge

**The Bank (Resource Protection/Management)**

* Purpose: Secure resource storage, town fund management
* Functions: Quest token banking, resource protection

**The WALL (City Wall)**

* Purpose: Town defense, expansion control
* Functions: Protection systems, territory control

### Building Upgrade Requirements

Each building has multiple upgrade levels requiring increasing amounts of materials and Quest tokens from your Town Bank. Higher levels unlock better recipes, faster processing times, and additional functionality.

## Advanced Features

### Looting System

* **Sleep Timer**: Critters become lootable 24 hours after completing gathering without claiming rewards
* **Visual Indicators**: Sleeping critters show golden shimmer effect
* **Instant Looting**: No travel time required - click to loot immediately
* **Availability**: Must have idle critter in town to perform looting
* **Competition**: First player to loot claims the rewards

### Competitive Elements

* **Mining Leaderboards**: Track top performers on each resource
* **First Completion Bonuses**: Extra rewards for first player to finish a node
* **Resource Competition**: Multiple players can gather from same nodes
* **Loot Racing**: Competition to claim sleeping critters

## Technical Information

### Blockchain Integration

* Built on Solana blockchain
* Critters are NFTs with individual locked Quest balances
* Town creation costs: \~0.05-0.06 SOL + token account creation fees
* All transactions require on-chain confirmation

### Performance Optimization

* **Known Issues**: M3/M4 Mac heating problems
* **Browser**: Chrome recommended with balanced performance settings
* **Mobile**: iPhone heating reported, Safari vs Chrome testing recommended
* **Refresh**: Many UI issues resolve with page refresh

### Troubleshooting

* **Error Messages**: Often indicate tool requirements not met or insufficient resources
* **Disappearing UI**: Usually resolved by refreshing page

## Getting Started Checklist

1. **Connect Email Wallet & Acquire Critter**
2. **Place Your Town** (location matters for initial resources)
3. **Deploy First Critter** to nearest Tier 1 resource
4. **Claim First Rewards**
5. **Build Mystic Mirror** (identify unknown recipes)
6. **Build Muddy Anvil** (craft better tools)
7. **Upgrade Town Level** (access higher tier resources)
8. **Craft Tier 3+ Tools** (unlock level scaling feature)
9. **Expand & Optimize** your resource gathering strategy

**Remember**: Critter actions use Locked Quest, Town development uses Town Bank Quest!


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://critters-quest-1.gitbook.io/critters-quest-docs/critter-quest-guides.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.