The Hytale Community Repository

About

Supported Content Types

Modtale is engineered to support the specific file structures and metadata requirements of Hytale's modification system:

• Modpacks: Curated collections of plugins and asset packs with automated dependency resolution.
• Server Plugins: Server-side JAR files executed by the Hytale server.
• Worlds: Maps, lobbies, and schematics.
• Art Assets: Models, textures, and client-side visuals.
• Data Assets: Configs, loot tables, and other data-driven properties.

---

Repository Structure

This monorepo houses the core components of the Modtale app:

modtale/
├── backend/                # Spring Boot REST API
│   ├── src/main/java/      # Application source code
│   └── build.gradle        # Backend dependencies & build config
├── frontend/               # Astro + React Web Application
│   ├── src/                # Components, pages, and styles
│   ├── astro.config.mjs    # Astro configuration
│   └── package.json        # Frontend dependencies & scripts
└── Warden/                 # (Closed Source) Security Scanner Service

---

Tech Stack

Domain	Technology	Version	Usage
Frontend	Astro	v4.3.5	Framework & Hybrid Routing (SSR/CSR)
	React	v19.2.1	UI Library & Interactive Islands
	Node.js	v20+	Runtime Environment
	Tailwind CSS	v3.4	Utility-first Styling System
	Lucide React	Latest	Iconography
Backend	Java	JDK 21	Server-side Language
	Spring Boot	v3.3.4	REST API Framework
	MongoDB	Latest	Primary NoSQL Data Store
	Bucket4j	v0.10.3	Rate Limiting (Token Bucket Algorithm)
	Caffeine	Latest	High-performance In-memory Caching
Infra	Cloudflare R2	N/A	S3-compatible Object Storage
	Docker	Latest	Containerization & Deployment

---

Local Development

Follow these steps to set up the development environment on your local machine.

Prerequisites

• Node.js: v20 or higher.
• Java JDK: Version 21 (Amazon Corretto or OpenJDK recommended).
• MongoDB: A local instance running on port 27017 or a valid Atlas connection string.

1. Clone the Repository

git clone https://github.com/Modtale/modtale.git
cd modtale

2. Backend Configuration

The backend relies on environment variables for configuration. You can set these in your IDE run configuration or export them in your terminal session.

Required Variables:

Variable	Description	Example (Local)
MONGODB_URI	MongoDB Connection String	mongodb://localhost:27017/modtale
R2_ACCESS_KEY	Storage Access Key	your_r2_access_key
R2_SECRET_KEY	Storage Secret Key	your_r2_secret_key
R2_ENDPOINT	Storage Endpoint URL	https://<accountid>.r2.cloudflarestorage.com
WARDEN_ENABLED	Set to false for local dev	false

Note on Warden: The "Warden" security scanner is closed source and not included in this repo. You must set WARDEN_ENABLED=false to run the backend locally. This enables a "Mock Mode" where all file scans return a mock "CLEAN" result.

Optional Variables (OAuth): To test login features, you will need valid OAuth credentials. If you skip these, the app will start, but login will fail.

• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET
• DISCORD_CLIENT_ID / DISCORD_CLIENT_SECRET
• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

3. Run the Backend

Navigate to the backend directory and run the application using Gradle.

cd backend
# Linux/Mac
./gradlew bootRun

# Windows
gradlew.bat bootRun

The API will initialize at http://localhost:8080.

4. Frontend Configuration

Create a .env file in the frontend/ directory to configure the API connection.

File: frontend/.env

# Points to your local backend instance
PUBLIC_API_URL=http://localhost:8080/api/v1

5. Run the Frontend

Navigate to the frontend directory, install dependencies, and start the dev server.

cd frontend
npm install
npm run dev

The web client will initialize at http://localhost:5173.

---

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

Modtale is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Community & Support

• Docs: modtale.net/api-docs
• Discord: Join the Server
• X (Twitter): @modtalenet
• Bluesky: @modtale.net

---

Contributing

Please refer to CONTRIBUTING.md for guidelines on submitting pull requests and reporting issues.

---

Star History

© 2026 Modtale. The Hytale Community Repository.