servermods/TUTORIAL.md

# How to Use the Server Modpack

This tutorial explains how players can install and use the automatically generated modpack to connect to the Minecraft server.

## Overview

The server uses an automated system to maintain a minimal client modpack that contains only the mods required to connect to the server, plus TACZ gun packs for enhanced gameplay. This modpack is published in Modrinth format and updated automatically whenever the server's mod list changes.

## Prerequisites

Before installing the modpack, you need:

1. **Minecraft Java Edition** version 1.20.1
2. **Forge Loader** for Minecraft 1.20.1 (recommended: latest stable version)
3. A modpack loader that supports Modrinth format (such as:
   - [Prism Launcher](https://prismlauncher.org/) (recommended)
   - [Modrinth App](https://modrinth.com/app)
   - [PolyMC](https://polymc.org/)
   - [ATLauncher](https://atlauncher.com/)
   - Or any launcher that supports Modrinth index files)

## Installation Methods

### Method 1: Using Prism Launcher (Recommended)

1. **Download and Install Prism Launcher**
   - Visit https://prismlauncher.org/download/
   - Download the version for your operating system
   - Install and launch the application

2. **Add the Modpack Repository**
   - In Prism Launcher, go to the "Instances" tab
   - Click the "+" button to add a new instance
   - Select "Modrinth" as the source type
   - In the "Modrinth URL or Index" field, paste:
     ```
     raw.githubusercontent.com/jianf/servermods/main/modpack/modrinth.index.json
     ```
     (Note: We'll use git directly since this is a private repository)

3. **Alternative: Direct Git Access**
   Since this is a private repository, you'll need to:
   - Clone the repository: `git clone ssh://git@jianfgit.xyz:220/jianf/servermods.git`
   - In Prism Launcher, when creating a new instance, choose "Import from ZIP" or "Import from Folder"
   - Navigate to the cloned repository's `modpack/` directory
   - Select the `modrinth.index.json` file

4. **Install the Modpack**
   - Prism Launcher will automatically download all required mods and gunpacks
   - It will create a new instance named "minimal-client-modpack"
   - Select the instance and click "Play"

### Method 2: Manual Installation

If you prefer to install manually:

1. **Download the Modpack Index**
   - Access the modpack index at: `ssh://git@jianfgit.xyz:220/jianf/servermods.git` (requires authentication)
   - Or download the `modrinth.index.json` file from the `modpack/` directory

2. **Create the Modpack Folder Structure**
   ```
   minimal-client-modpack/
   ├── mods/
   └── tacz/
   ```

3. **Download Required Files**
   For each file listed in the `modrinth.index.json` under the `files` array:
   - If the path starts with `mods/` → place the file in the `mods/` folder
   - If the path starts with `tacz/` → place the file in the `tacz/` folder
   - You can obtain these files from the server administrator or by requesting them directly

4. **Install Forge**
   - Download Forge 1.20.1 from https://files.minecraftforge.net/
   - Run the installer and select "Install client"

5. **Launch Minecraft**
   - In your Minecraft launcher, create a new installation
   - Select the Forge version you installed
   - Set the game directory to your `minimal-client-modpack` folder
   - Launch the game

## Important Notes

### Version Matching
- The modpack version MUST match exactly what the server expects
- If you see a "Failed to handshake with server" or "Invalid session" error, it's likely a version mismatch
- Always ensure you have the latest version by updating your modpack regularly

### Updating the Modpack
- The modpack updates automatically on the server every 12 hours
- To update your client:
  - **Prism Launcher**: Select the instance and click the "Update" arrow
  - **Manual**: Download the latest `modrinth.index.json` and redownload any files with changed hashes
  - **Git method**: `git pull` in your cloned repository and refresh the modpack in your launcher

### Troubleshooting

#### "Missing Mods" Error
1. Verify all files listed in `modrinth.index.json` are present in your `mods/` and `tacz/` folders
2. Check that file names match exactly (case-sensitive)
3. Verify you downloaded the correct versions by checking SHA1 hashes (advanced)

#### "Mod Loading Error" or Crash
1. Ensure you're using Forge 1.20.1, not a different version
2. Check that no conflicting mods are installed outside the modpack folder
3. Try removing all mods and reinstalling from scratch using the index

#### Connection Issues
1. Confirm the server address is correct
2. Verify your internet connection
3. Check that the server is online and not maintenance
4. Ensure your modpack version matches the server's current version

## For Server Administrators

### How the System Works

1. **Monitoring**: The system watches `/tmp/server_mods.txt` for changes
2. **Detection**: When mods are added/removed, it detects the change
3. **Packaging**: It creates a Modrinth index file with all required mods and TACZ gun packs
4. **Versioning**: Uses decimal versioning (0.0.1, 0.0.2, etc.) incrementing on each change
5. **Deployment**: Commits and pushes to the git repository at `ssh://git@jianfgit.xyz:220/jianf/servermods.git`

### Manual Trigger
To force an update outside the 12-hour cycle:
```bash
/tmp/mod_repo/sync_modpack.sh
```

### Checking Status
```bash
# Check if timer is active
systemctl list-timers --all | grep modpack

# View recent logs
journalctl -u modpack-sync.service --since "1 hour ago"

# Check current version
cat /tmp/mod_repo/VERSION
```

### Adding New Mods
1. Place the mod `.jar` file in `/home/minecraft/mods/`
2. Add the mod name (without version suffix) to `/tmp/server_mods.txt`
3. Wait for the next sync cycle or run the script manually
4. Notify players to update their modpacks

## Technical Details

### Modrinth Index Format
The modpack uses the official Modrinth index format version 1. Key fields:
- `formatVersion`: 1
- `game.type`: "forge"
- `game.version`: "1.20.1"
- `versionId`: Decimal version (e.g., "0.0.3")
- `files.array`: List of objects containing:
  - `path`: File location within modpack (`mods/` or `tacz/`)
  - `hashes.sha1`: SHA1 hash for file verification
  - `env.client`: ["required"] - needed on client
  - `env.server`: ["unsupported"] - not needed/allowed on server
  - `downloads`: [] - empty as we use direct file distribution

### Why Minimal Modpack?
- Reduces client load times and memory usage
- Ensures compatibility by only including server-required mods
- Lowers barrier to entry for players with older hardware
- Prevents conflicts from unnecessary client-side mods

### TACZ Integration
TACZ (gun) packs are treated as regular mods but stored in a `tacz/` subfolder for organization. They are required for the full gameplay experience on this server.

## Support

If you encounter issues:
1. Check that you're using the latest modpack version
2. Verify your Minecraft and Forge versions are correct (1.20.1)
3. Ensure all files are present and correctly named
4. Contact server administrators with:
   - Your Minecraft version
   - Your Forge version
   - The exact error message
   - List of files in your `mods/` and `tacz/` folders

Happy crafting!