148 lines
4.3 KiB
Markdown
148 lines
4.3 KiB
Markdown
<p align="center">
|
|
<img src="public/images/logo.png" alt="Terraria" width="400">
|
|
</p>
|
|
|
|
<h1 align="center">Terraria Companion</h1>
|
|
|
|
<p align="center">
|
|
A self-contained web app for searching Terraria items, exploring crafting trees, and tracking recipe progress — all powered by data from the <a href="https://terraria.wiki.gg">Terraria Wiki</a>.
|
|
</p>
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Item Search** — Fast, ranked search across 5000+ Terraria items (exact > prefix > contains)
|
|
- **Crafting Trees** — Recursive visualization of crafting recipes with ingredients and stations
|
|
- **Drop Information** — See which enemies and bosses drop an item, with quantity and drop rates
|
|
- **Pinned Recipes** — Save favorite recipes for quick reference
|
|
- **Owned Item Tracking** — Mark ingredients you already have; tracks progress per recipe
|
|
- **Auto-Collapse** — Owned items in recipe trees collapse automatically to reduce clutter
|
|
- **Terraria-Style Tooltips** — Hover over items to see damage, defense, knockback, sell price, and more
|
|
- **Light / Dark Mode** — Adapts to your system color scheme
|
|
- **Single Binary** — Everything embeds into one executable with zero external dependencies
|
|
- **Cross-Platform** — Builds for Linux and macOS (amd64 and arm64)
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- [Go 1.24+](https://go.dev/dl/)
|
|
|
|
### 1. Fetch data from the Terraria Wiki
|
|
|
|
```bash
|
|
make fetch
|
|
```
|
|
|
|
This downloads items, recipes, drops, and icons into the `data/` and `public/icons/` directories. The process is resumable — if interrupted, just run it again.
|
|
|
|
### 2. Build and run
|
|
|
|
```bash
|
|
make serve
|
|
```
|
|
|
|
Open [http://localhost:3000](http://localhost:3000) in your browser.
|
|
|
|
### Development mode
|
|
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
Serves frontend assets from disk and hot-reloads data files on change.
|
|
|
|
## Usage
|
|
|
|
| Action | How |
|
|
|---|---|
|
|
| Search for an item | Type in the search box (min 2 characters) |
|
|
| View crafting tree | Click any item from search results |
|
|
| See drop sources | Scroll down on an item page |
|
|
| Pin a recipe | Click the pin icon on a recipe |
|
|
| Track owned items | Check the boxes next to ingredients you have |
|
|
| View pinned recipes | Navigate to `/pins` |
|
|
|
|
## Deployment
|
|
|
|
### Docker Compose
|
|
|
|
```yaml
|
|
services:
|
|
terraria-companion:
|
|
image: git.nakama.town/fmartingr/terraria-companion:latest
|
|
restart: unless-stopped
|
|
ports:
|
|
- "3000:3000"
|
|
volumes:
|
|
- ./data:/app/data:ro
|
|
- ./public/icons:/app/public/icons:ro
|
|
environment:
|
|
- PORT=3000
|
|
```
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Standalone binary
|
|
|
|
```bash
|
|
# Build with embedded data (single portable executable)
|
|
make build
|
|
|
|
# Run it
|
|
./terraria-companion
|
|
```
|
|
|
|
### Environment variables
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `PORT` | `3000` | HTTP server port |
|
|
| `DEV` | _(unset)_ | Set to any value to enable development mode |
|
|
|
|
## API
|
|
|
|
All endpoints return JSON.
|
|
|
|
| Endpoint | Parameters | Description |
|
|
|---|---|---|
|
|
| `GET /api/search` | `q` (min 2 chars) | Search items by name |
|
|
| `GET /api/item` | `name` | Get a single item |
|
|
| `GET /api/recipes` | `item` | Get crafting recipes for an item |
|
|
| `GET /api/drops` | `item` | Get drop sources for an item |
|
|
| `GET /api/splashes` | — | Get random splash text strings |
|
|
| `GET /api/status` | — | Server status and item counts |
|
|
|
|
## Building
|
|
|
|
```bash
|
|
make help # Show all available targets
|
|
make build # Production binary with embedded data
|
|
make build-nodata # Binary that reads data from disk at runtime
|
|
make build-snapshot # Cross-platform builds via goreleaser
|
|
make fetch # Fetch/resume wiki data
|
|
make fetch-reset # Reset and fetch from scratch
|
|
make dev # Development mode with hot-reload
|
|
make format # Format Go source
|
|
make lint # Run linter
|
|
make clean # Remove build artifacts
|
|
make clean-data # Remove fetched data
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/my-feature`)
|
|
3. Fetch the data (`make fetch`)
|
|
4. Run in dev mode (`make dev`)
|
|
5. Make your changes
|
|
6. Format and lint (`make format && make lint`)
|
|
7. Commit and push
|
|
8. Open a pull request
|
|
|
|
## License
|
|
|
|
This project fetches data and images from the [Terraria Wiki](https://terraria.wiki.gg). Terraria is developed by [Re-Logic](https://re-logic.com). All game assets and data belong to their respective owners.
|