Derity™

# Derity - Minecraft Fabric Mod 1.21.1

A talking **red mixed blue ball** that chats with you via **OpenRouter AI**, plus a cursed **Derity Stick** that kills you, screams, and launches you!

## Features

### 1. Derity Entity - The Talking Ball
- **Appearance**: 14x14x14 cube ball with red-blue gradient (half red `#E53935`, half blue `#1E88E5`, purple blend in middle), white eyes with pupils, shiny highlight, little antenna
- **Movement**:
  - Bouncy physics: bounces on ground with momentum, squashes/stretches
  - Floating/drifting in air, occasional hover (no gravity toggle)
  - Orbits nearby players within 8 blocks
  - Wall bounce with sound
  - No fall damage, spins and wobbles while moving
  - Shadow radius 0.45
- **Chat AI (OpenRouter)**:
  - Say `Derity <your message>` in chat (e.g., `Derity hello!`, `Derity who are you?`)
  - If a Derity is within 32 blocks, it responds via OpenRouter (`openai/gpt-4o-mini` by default)
  - Response is broadcast as `<Derity> ...` and the nearest Derity entity jumps, shows nameplate, plays sound
  - Works async, no lag
  - Fallback local responses if no API key set (funny ball lines with *bounces* *spins*)
  - Interact (right-click) Derity for greeting and bounce

### 2. Derity Stick - Red & Blue Mixed Stick
- **Texture**: Diagonal 16x16 stick, gradient red→blue with glow in middle, dark purple outline
- **Recipe**: 
  ```
  R
  B
  S
  ```
  R = Red Dye, B = Blue Dye, S = Stick → 1 Derity Stick
- **Use (Right-click)**:
  - **SCREAMS**: plays `derity_scream` (warden sonic boom + ghast scream) at volume 2.0
  - **Movement**: launches you `(±1, 1.8-2.6, ±1)` velocity, adds Nausea 10s, Blindness 3s, Slowness
  - **Particles**: Soul, Sonic Boom, Explosion
  - **Broadcast**: `☠ <player> was consumed by the Derity Stick! AAAAAAAH!!!`
  - **Kills you** after 0.8s delay (magic damage, bypass armor, kills even in creative if possible)
  - Damages stick (5 uses), 2s cooldown
- **AttackEntity**: hitting any entity with stick also screams and kills attacker (betrayal!)

### 3. Sounds (proxied to vanilla)
- `derity_talk` → `entity/slime/squish`
- `derity_bounce` → `entity/slime/jump`
- `derity_hurt` → `entity/slime/hurt`
- `derity_death` → `entity/slime/death`
- `derity_scream` → `entity/warden/sonic_boom` + `entity/ghast/scream`

## Installation

1. Requires **Fabric Loader 0.16.10** + **Fabric API 0.107.0+1.21.1** + **Minecraft 1.21.1** + **Java 21**
2. Build: `.\gradlew.bat build` → `build/libs/derity-1.0.0.jar`
3. Put jar in `mods/` folder
4. Run game, spawn Derity via `/summon derity:derity` or spawn egg (Tools/Spawn Eggs creative tabs)

## OpenRouter Setup (for Chat AI)

1. Get API key at https://openrouter.ai/keys
2. Run game once to generate `config/derity.json`
3. Edit `config/derity.json`:
```json
{
  "openRouterApiKey": "sk-or-v1-...your key...",
  "openRouterModel": "openai/gpt-4o-mini",
  "systemPrompt": "You are Derity, a playful talking red and blue mixed ball...",
  "temperature": 0.9,
  "maxTokens": 150,
  "siteUrl": "https://github.com/derity/mod",
  "siteName": "Derity Minecraft Mod"
}
```
4. Restart world/server. Talk: `Derity what's the meaning of life?`
5. Without key, Derity uses funny local fallbacks.

**Direct file**: `src/main/java/com/riority/derity/config/DerityConfig.java:16` and `src/main/java/com/riority/derity/util/OpenRouterClient.java:22`

## Commands & Testing

- `/summon derity:derity ~ ~1 ~` — summon ball at feet
- Give stick: `/give @p derity:derity_stick`
- Give egg: `/give @p derity:derity_spawn_egg`
- Chat: `Derity hello` → see `<Derity> *bounces* HIII!!...`
- Use stick → get launched, hear WARDEN boom, die

## Files of Interest

- Entity: `src/main/java/com/riority/derity/entity/DerityEntity.java:25` — bouncy physics, `tickMovementLogic()`
- Stick: `src/main/java/com/riority/derity/item/DerityStickItem.java:22`
- AI Client: `src/main/java/com/riority/derity/util/OpenRouterClient.java:11`
- Mod init: `src/main/java/com/riority/derity/DerityMod.java:18` — chat listener `ServerMessageEvents.ALLOW_CHAT_MESSAGE`
- Renderer: `src/main/java/com/riority/derity/client/DerityEntityRenderer.java:16` — squash/stretch, spin
- Model: `src/main/java/com/riority/derity/client/DerityEntityModel.java:10` — Layer `derity:derity`
- Textures: `src/main/resources/assets/derity/textures/entity/derity.png` (generated) and `.../item/derity_stick.png`
- Sounds: `src/main/resources/assets/derity/sounds.json:1`
- Recipe: `src/main/resources/data/derity/recipe/derity_stick.json:1`

## Movement Details

- **On Ground**: `hy = 0.42 + rand*0.25`, `hx/z ±0.3`, `playSound BOUNCE`
- **Mid-air**: 8% chance random drift, 3% hover (noGravity true), 2% fall
- **Orbit**: every tick, 1.5% chance to orbit nearest player `Vec3(-toPlayer.z, 0.05, toPlayer.x) *0.12`
- **Wall**: `horizontalCollision` → `velocity *= -0.7, y+0.2`
- **Renderer**: `scaleX/Z = 1 + squash*0.6`, `scaleY = 1 - squash`, spin `12°/tick`, wobble `sin/cos` tilt, bob `sin(0.3)*0.08`

## Building

```bat
.\gradlew.bat build        # → build/libs/derity-1.0.0.jar
.\gradlew.bat runClient    # test client
.\gradlew.bat runServer    # test server
```

## Credits

- Fabric Example Mod template
- OpenRouter (https://openrouter.ai)
- Textures generated via PIL (red `#E53935` + blue `#1E88E5`)

Enjoy Derity! *bounces* *wobbles* *screams when you touch the stick*