@zerospacegg/vynthra/README.md

Discord bot for ZeroSpace.gg data

# Vynthra

[![NPM Version](https://img.shields.io/npm/v/@zerospacegg/vynthra)](https://www.npmjs.com/package/@zerospacegg/vynthra)
[![License](https://img.shields.io/npm/l/@zerospacegg/vynthra)](https://github.com/zerospace-gg/zsgg/blob/main/vynthra/LICENSE)
[![Repository](https://img.shields.io/badge/repo-zerospace--gg%2Fzsgg-blue)](https://github.com/zerospace-gg/zsgg/tree/main/vynthra)

Discord bot and library for ZeroSpace.gg entity data. Provides entity search, markdown rendering, and a full Discord bot implementation.

## Overview

Vynthra is a TypeScript library that provides search functionality for ZeroSpace.gg game entities (factions, units, buildings, maps, etc.) from the `@zerospacegg/iolin` data package. It includes fuzzy search capabilities and markdown rendering for both Discord messages and terminal output.

## Features

- **Discord Bot**: Full Discord bot with `/zsgg stats` slash command
- **Entity Search**: Search game entities by ID, slug, or name with fuzzy matching
- **Markdown Generation**: Generate markdown suitable for Discord messages
- **Terminal Display**: Render search results with colored terminal output
- **TypeScript Support**: Full type safety with TypeScript definitions

## Installation

```bash
# As an NPM package
npm install @zerospacegg/vynthra

# Or from monorepo root
pnpm install

# Build the project
cd vynthra
npm run build
```

## Usage

### Discord Bot

Set up and run the Discord bot:

```bash
# Copy configuration template
cp bot-config.sample.json bot-config.json

# Edit bot-config.json with your Discord credentials
# OR set environment variables:
export DISCORD_TOKEN="your_bot_token"
export DISCORD_CLIENT_ID="your_client_id"

# Deploy slash commands
npm run bot:deploy

# Start the bot
npm run bot:start
```

See [BOT_SETUP.md](./BOT_SETUP.md) for detailed setup instructions.

### Command Line Tool

The project also includes a CLI tool for testing and prototyping:

```bash
# Search for entities
node bin/stats.js grell
node bin/stats.js "marran badger"
node bin/stats.js faction/legion
```

### Library Usage

```typescript
import { searchEntities, renderSearchResultAsMarkdown } from '@zerospacegg/vynthra';

// Search for entities
const result = searchEntities('grell');

// Generate markdown for Discord
const markdown = renderSearchResultAsMarkdown(result);

// Generate terminal output
const terminal = renderSearchResultToTerminal(result);
```

## Search Types

The search function returns different result types:

- **Single Match**: Exact match found, returns full entity data
- **Multiple Matches**: Fuzzy search found multiple possibilities
- **No Match**: No entities found matching the query

## Search Priority

1. Exact ID match (e.g., `faction/grell`)
2. Exact slug match (e.g., `grell`)
3. Exact name match (case insensitive)
4. Fuzzy matching on ID, slug, and name

## Examples

```bash
# Exact matches
node bin/stats.js grell                    # Finds Grell faction
node bin/stats.js faction/grell           # Direct ID lookup

# Fuzzy matching
node bin/stats.js badger                  # Finds Marran Badger
node bin/stats.js marine                  # Shows multiple matches

# No matches
node bin/stats.js nonexistent             # Shows helpful error message
```

## Development

```bash
# Watch mode for development
npm run dev

# Type checking
npm run lint

# Clean build artifacts
npm run clean
```

## Project Structure

```
src/
├── lib/
│   ├── index.ts       # Main entry point
│   ├── search.ts      # Entity search functionality
│   ├── fuzzy.ts       # Fuzzy matching utilities
│   ├── renderer.ts    # Markdown and terminal rendering
│   └── types.ts       # TypeScript type definitions
├── bot/
│   ├── index.ts       # Discord bot entry point
│   ├── client.ts      # Bot client implementation
│   ├── deploy.ts      # Command deployment utilities
│   ├── types.ts       # Bot-specific types
│   └── commands/
│       └── stats.ts   # /zsgg stats command
└── bin/
    ├── stats.js       # CLI tool
    └── bot.js         # Discord bot CLI
```

## Discord Commands

### `/zsgg stats <query>`

Search for game data and get detailed stats:

- `/zsgg stats grell` - Get Grell faction information
- `/zsgg stats terror tank` - Get Terror Tank unit stats  
- `/zsgg stats foundry` - Get building information
- `/zsgg stats dust bowl` - Get map details

Supports fuzzy matching and handles partial names automatically.

## Future Plans

- Additional Discord slash commands
- Advanced filtering options
- Entity comparison features
- Interactive search interface

## Repository

This package is part of the [ZeroSpace.gg monorepo](https://github.com/zerospace-gg/zsgg).

- **Source Code**: [github.com/zerospace-gg/zsgg/tree/main/vynthra](https://github.com/zerospace-gg/zsgg/tree/main/vynthra)
- **Issues**: [github.com/zerospace-gg/zsgg/issues](https://github.com/zerospace-gg/zsgg/issues)
- **NPM Package**: [@zerospacegg/vynthra](https://www.npmjs.com/package/@zerospacegg/vynthra)

## License

ISC License - see [LICENSE](./LICENSE) file for details.

## Author

baby shoGGoth and ZeroSpace.gg