# Smily

Smily is a companion mod. A small, friendly face that lives in your world,

talks with you in chat, and actually helps out — finds ore, hands you items,

patches you up, and puts on a record when the evening gets quiet.

It works completely offline. No account and no setup required.

---

## Getting started

The first time you join a world, you'll receive a **Box**.

Place it, step back, and watch: it rises into the air and opens — and Smily

is there. A **README.txt** drops alongside it. Right-click the file to read

it like a book.

That's it. Now just talk in chat while standing near Smily.

---

## What Smily can do

Type normally in chat while Smily is within 10 blocks:

- **hello / who are you / how are you** — Smily chats back

- **cure me** — restores your health

- **where is the nearest diamond** — locates coal, iron, gold, lapis,

diamond or emerald and gives you the coordinates

- **give me 32 torches** — hands over almost any item (up to 100 at once)

- **2 + 2** or **10 * 3** — Smily does the maths

- **play some music / stop the music** — puts on a record

- **sorry / thank you / goodbye** — Smily responds

**Right-click Smily** to pick it up and carry it with you.

Type **/smilyhelp** in chat for the full list in game.

---

## Sadly

Smily has an opposite: **Sadly** — blue, quiet, and not in the mood to talk.

Ask Sadly anything and you'll get a shrug at best.

Sadly doesn't appear naturally anywhere in the world. You'll only find it in

the creative inventory, or by summoning it. It can be picked up and placed

just like Smily.

---

## Features

- Smily and Sadly animate their mouths while speaking

- Optional narrator voice reads their lines aloud

- Light or dark colour scheme for Smily

- Background music, toggled by asking

- Smily notices the world around it: biome, time of day, what's nearby

- Smily comes back if something happens to it

- Everything above works fully offline

---

## AI features (optional, OFF by default)

Smily can optionally use the **Groq API** to hold a real conversation instead

of using its built-in replies. This is completely optional — the mod ships

with it **disabled**, and it stays disabled unless you turn it on yourself.

### What it costs

Nothing. Groq has a free tier with no credit card required.

### How to set it up

1. Go to **console.groq.com** and create a free account

2. Open the **API Keys** section and create a new key

3. In Minecraft, open **Mods → Smily → Config**

4. Set **AI chat** to **ON**

5. Paste your key into the **Groq API key** field

6. Press **Done** and rejoin your world

Default model is `llama-3.1-8b-instant`. You can change it in the same screen.

Free tier limits are 30 requests per minute and 14,400 per day, which is far

more than a single-player world will ever use.

### What gets sent, and where

Please read this before enabling it:

- **Nothing is sent while the feature is off.** With AI disabled the mod makes

no network connections at all.

- Requests go to **one endpoint only**: https://api.groq.com/openai/v1/chat/completions

- A request contains the message you typed plus in-game context so the reply

makes sense: your coordinates, biome, time of day, blocks near Smily, and

your inventory contents.

- Requests are sent **with your own API key**. The mod ships no key, and the

author runs no server of any kind.

- There is **no telemetry and no analytics**. Nothing is sent to the author or

to any third party, and nothing is stored anywhere.

- Your API key is saved only in your local config file. Never share that file,

and never post screenshots of it.

Even with AI enabled, all in-game actions (finding ore, giving items, healing,

music) still run on the mod's own local logic.

---

## Config

Open **Mods → Smily → Config** in game:

**Personalization**

- Smily colour — light (yellow) or dark (black)

- Voice (narrator) — read Smily's lines aloud

**AI**

- AI chat — on/off master switch

- Groq API key

- Model

---

## Credits

**Music:** "Kater Street Rag" performed by Bennie Moten.

Public domain recording, courtesy of the Internet Archive Free 20s Jazz

Collection.

**Inspiration:** This mod was inspired by **Verity JE**, which showed me how

much personality a single companion can carry. Smily grew into its own thing,

but the spark came from there.

---

## Versions

Available for **Minecraft 1.12.2** and **1.16.5** (Forge).

Smily mod