# Kodama Companion Mod

A little forest spirit that follows you around in Mineclonia!

## Features

- Smooth orbiting movement — gentle, natural hovering
- Look-at reaction — Kodama notices when you gaze at it, drifts closer, and responds with a curious sound
- Hostile mob detection — Kodama glows and alerts you to danger
- Happiness mechanic — needs petting every 60 seconds (visual + sound only — no speed penalty)
- Recorder integration — play C - E - G on the recorder to summon your Kodama
- 6 Color Variants — Blue, Green, Gold, Purple, Red, and Default
- Custom sounds — summon song, look-at reaction, sleep sound, and more
- Glows in the dark
- Custom particle effects (happy, sad, alert, magic, summon, sleep)
- Persistent storage — your bond AND color choice survive server restarts
- Leaves with a sad little tap if neglected for 150 seconds

## How to Earn a Kodama

Plant saplings! Each time you plant a tree, there's a chance a Kodama will appear and bond with you. The forest rewards those who care for it.

## Interacting with Kodama

| Action | Result |
|--------|--------|
| Right-click | Pet your Kodama — resets happiness timer |
| Crouch + Left-click | Send Kodama to sleep (dismiss — use /kodama_call to wake it) |
| Look at Kodama | It notices you. Slows down, drifts closer, plays a soft sound |
| Play C - E - G on recorder | Summon song — Kodama appears beside you |

## Commands

| Command | Description |
|---------|-------------|
| /kodama_call | Summon your Kodama companion (if you have earned one) |
| /kodama_leave | Dismiss your Kodama (returns to the forest — can be summoned again) |
| /kodama_time | Check how long since you last pet your Kodama |
| /kodama_status | Check if you have earned a Kodama and your current color |

### Color Commands

| Command | Description |
|---------|-------------|
| /kodama_blue | Change your Kodama to blue |
| /kodama_green | Change your Kodama to green |
| /kodama_gold | Change your Kodama to gold |
| /kodama_purple | Change your Kodama to purple |
| /kodama_red | Change your Kodama to red |
| /kodama_default | Change your Kodama back to default |

Colors are saved permanently. Your Kodama will remember its color even after server restarts.

## Happiness Timeline

| Time since last pet | Effect |
|---------------------|--------|
| 0 – 60 seconds | Happy — normal behavior |
| 60 – 120 seconds | Sad — sad particles, soft whimpers (no speed penalty) |
| 120 – 150 seconds | Very sad — warning sounds, might leave soon |
| 150+ seconds | Leaves forever — you must plant trees to earn a new one |

Right-click your Kodama to pet it and reset the timer. The spirit never moves slower — only its heart shows the sadness.

## The Summon Song

Once you've earned a Kodama, you can call it anytime by playing C - E - G on the recorder. The forest remembers its friends.

## Custom Sounds (Optional)

Place these .ogg files in kodama_companion/sounds/:

| Filename | When it plays |
|----------|----------------|
| whatup.ogg | Player looks at Kodama |
| summonsong.ogg | Summon song (recorder or command) |
| sleepsound.ogg | Crouch + left-click to dismiss |

Missing sound files will not cause errors — they simply won't play.

## Admin Commands

| Command | Description |
|---------|-------------|
| /kodama_reset <player> | Reset a player's earned Kodama status and color (requires server privilege) |

## Dependencies

- Required: None (standalone)
- Recommended: mobs_mc — for hostile mob detection
- Optional: recorder — for summon song integration

## License

CC0 1.0 Universal (Public Domain) — You can copy, modify, distribute, and perform the work, even for commercial purposes, all without asking permission.

## Version History

| Version | Notes |
|---------|-------|
| Beta 0.0.6 | The Summon Song — Recorder integration, look-at reaction, custom sounds, no sad speed penalty, crouch+left-click to sleep |
| Beta 0.0.5 | Added 6 color variants with persistent storage, color commands |
| Beta 0.0.4 | Persistent storage, optimized scanning, threat detection, random seeding fix |
| Beta 0.0.3 | Initial release on ContentDB |

Plant trees, find Kodama, choose your color, play the summon song, and may the forest watch over you.
