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 (recommended)
   • Modrinth App
   • PolyMC
   • ATLauncher
   • 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:

/tmp/mod_repo/sync_modpack.sh

Checking Status

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