Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

AstralBot is a Minecraft mod and Discord bot hybrid written in Kotlin that bridges communication between Minecraft servers and Discord communities. It features a multi-loader architecture supporting both Fabric and Forge for Minecraft 1.18.2.

## Common Commands

### Build System
```bash
./gradlew build # Build all modules
./gradlew publishMods # Publish to Modrinth and CurseForge
./gradlew fabric:build # Build Fabric version only
./gradlew forge:build # Build Forge version only
./gradlew tasks # List all available tasks
```

### Development
```bash
./gradlew fabric:runClient # Run Fabric client
./gradlew fabric:runServer # Run Fabric server
./gradlew forge:runClient # Run Forge client
./gradlew forge:runServer # Run Forge server
```

## Architecture

The project uses a multi-loader architecture with three main modules:

- **common/**: Core business logic and shared code in Kotlin
- **fabric/**: Fabric-specific implementations and event handling
- **forge/**: Forge-specific implementations and event handling

### Key Components

- `Bot.kt` - Main bot orchestrator and lifecycle management
- `MinecraftHandler` - Handles Minecraft ↔ Discord communication
- `FAQHandler` - Manages FAQ system with file watching
- `WhitelistHandler` - Discord-based whitelist management
- `commands/discord/` - Discord slash commands
- `commands/minecraft/` - Minecraft server commands

### Technology Stack

- **Language**: Kotlin 2.1.10 with Java 17
- **Discord API**: JDA v5.1.2
- **Database**: SQLite with JetBrains Exposed ORM
- **Configuration**: Forge Config API (cross-platform)
- **Documentation**: CommonMark for Markdown parsing

## Configuration

Main configuration files:
- `astralbot-server.toml` - Bot configuration
- `astralbot-text.toml` - Customizable text messages
- `gradle.properties` - Version and build configuration

Environment variables:
- `DISCORD_TOKEN` - Discord bot token (required)

## Dependency Management

The project uses Gradle version catalogs for organized dependency management:
- `libs.versions.toml` - Core dependencies
- `gradle/jda.versions.toml` - Discord API dependencies
- `gradle/dcwebhooks.versions.toml` - Webhook dependencies
- `gradle/exposed.versions.toml` - Database dependencies

## Development Notes

- All Discord API dependencies are bundled into the mod
- Use coroutines for async operations
- Platform-specific code goes in respective `fabric/` or `forge/` modules
- Shared logic belongs in `common/` module
- FAQ files support live reloading without server restart
- Database connections are configurable but default to SQLite

## Branch Strategy

- `develop` - Main development branch
- `main` - Stable releases
- `version/*` - Version-specific branches
92 changes: 92 additions & 0 deletions CURSOR_SETUP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Cursor Setup for AstralBot

## Quick Setup for Cursor

### 1. Install Cursor
- Download from: https://cursor.sh/
- Install and launch Cursor

### 2. Open the Project
```bash
# In Cursor, open the AstralBot directory
File → Open Folder → /home/boss/IdeaProjects/AstralBot
```

### 3. Essential Extensions for Cursor

Install these extensions via the Extensions panel (Ctrl+Shift+X):

#### Core Extensions
- **Kotlin Language** (`mathiasfrohlich.Kotlin`)
- **Kotlin Extension Pack** (`fwcd.kotlin`)
- **Gradle for Java** (`vscjava.vscode-gradle`)
- **Java Extension Pack** (`vscjava.vscode-java-pack`)

#### Development Tools
- **GitLens** (`eamodio.gitlens`) - Enhanced Git integration
- **Bracket Pair Colorizer 2** (`CoenraadS.bracket-pair-colorizer-2`)
- **Material Icon Theme** (`PKief.material-icon-theme`)
- **SonarLint** (`SonarSource.sonarlint-vscode`) - Code quality

### 4. Cursor Settings

The project already includes optimized settings in `.vscode/settings.json`:
- Java 17 configuration
- Kotlin language server enabled
- Auto-formatting on save
- Build directories excluded from search

### 5. AI Assistant Configuration

Cursor's AI is already configured for:
- **Kotlin development** - Excellent Kotlin code suggestions
- **Minecraft modding** - Understands Minecraft APIs
- **Discord bot development** - JDA library knowledge
- **Gradle builds** - Build system assistance

### 6. Quick Commands

```bash
# Setup environment
./setup.sh

# Build project
./gradlew build

# Run specific modules
./gradlew :fabric:build
./gradlew :forge:build
```

### 7. Cursor AI Tips

- **Ask for code explanations**: "Explain this Minecraft mixin"
- **Request refactoring**: "Refactor this Discord command handler"
- **Get debugging help**: "Why is this Kotlin coroutine not working?"
- **Ask for best practices**: "What's the best way to handle Minecraft events?"

### 8. Project Structure in Cursor

```
AstralBot/
├── common/ # Shared Kotlin code
├── fabric/ # Fabric-specific code
├── forge/ # Forge-specific code
├── .vscode/ # Cursor/VS Code settings
└── gradle/ # Build configuration
```

### 9. Next Steps

1. **Open the project** in Cursor
2. **Install the extensions** listed above
3. **Run the setup script**: `./setup.sh`
4. **Build the project**: `./gradlew build`
5. **Start coding** with AI assistance!

The project is now ready for development in Cursor with full AI support for Kotlin, Minecraft modding, and Discord bot development.





Loading