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

# 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:

# 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 for detailed setup instructions.

Command Line Tool

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

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

Library Usage

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

# 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

# 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.

• Source Code: github.com/zerospace-gg/zsgg/tree/main/vynthra
• Issues: github.com/zerospace-gg/zsgg/issues
• NPM Package: @zerospacegg/vynthra

License

ISC License - see LICENSE file for details.

Author

baby shoGGoth and ZeroSpace.gg