Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lDEVinux/eaglercraft/llms.txt

Use this file to discover all available pages before exploring further.

Eaglercraft uses EPK (Eaglercraft Package) files to bundle game assets — textures, sounds, models, and more. You can create a custom resource pack by editing assets in the repository and recompiling the EPK, then deploying it to your hosted client.

​
What is an EPK File?

EPK is a compressed archive format specific to Eaglercraft. When the client loads, it fetches assets.epk (the path configured in assetsURI) and unpacks all game assets from it. The archive contains:
  • All block, item, and entity textures
  • In-game sounds and music tracks
  • Font, GUI, and other UI resources
  • Miscellaneous game data files
The EPK is generated from the source tree under lwjgl-rundir/resources/ by the epkcompiler/ tooling included in the repository.

​
Prerequisites

  • Java must be installed. You can download it from java.com.
  • A local copy of the Eaglercraft repository (clone or fork) that includes the lwjgl-rundir/resources/ folder with all source assets.

​
Editing Assets

1

Clone or copy the repository

Obtain a local copy of the Eaglercraft repository so you have access to the lwjgl-rundir/resources/ source asset tree.
2

Edit files in lwjgl-rundir/resources/

Modify textures (.png), sounds (.mp3, .ogg), or any other files inside lwjgl-rundir/resources/. These are the source assets that will be packaged into the EPK.
3

Navigate to the epkcompiler/ folder

Open a terminal (or File Explorer on Windows) and go to the epkcompiler/ directory in the repository root.
4

Compile the EPK

Run the compiler script for your operating system:
:: Navigate to epkcompiler/ and run:
run.bat
:: Wait for "Press any key to continue..."
Both scripts invoke the same underlying command:
java -jar CompilePackage.jar "../lwjgl-rundir/resources" "../javascript/assets.epk"
This reads every file from lwjgl-rundir/resources/ and writes the compiled archive to javascript/assets.epk.

​
Deploying Your Resource Pack

1

Locate the compiled assets.epk

After compilation finishes, the updated archive is written to javascript/assets.epk inside the repository.
2

Copy assets.epk to your web server

Upload javascript/assets.epk to your web server, replacing the existing assets.epk file that your hosted client currently serves.
3

Clear browser cache and verify

Hard-refresh the page or clear your browser cache, then reload the client. Your custom textures, sounds, or other assets should now be active.
Only modify files inside lwjgl-rundir/resources/. Do not commit changes to javascript/assets.epk or javascript/classes.js if you are contributing back to the repository — the maintainers recompile those files themselves when merging pull requests.

​
Asset Overrides (No EPK Recompile)

If you only need to replace a small number of files — most commonly music tracks — you can use the assetOverrides option in eaglercraftOpts to swap individual EPK paths for external URLs at runtime, without touching the EPK file at all.
index.html
assetOverrides: {
  "records/wait.mp3":    "wait.mp3",                                     // local file
  "records/mellohi.mp3": "https://stream.nightride.fm/chillsynth.m4a",  // remote stream
  "records/far.mp3":     "https://stream.nightride.fm/nightride.m4a"
}
This approach is ideal for replacing music with live radio streams or self-hosted audio files without recompiling the EPK. For full details and all supported options, see the eaglercraftOpts reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us