Getting Started

Creating your first pack

Creating a Packin pack is super simple.

PackinResourcePack.create(PackMetadata("Test Title", Text.literal("Test description"))) {
    //
}

You can export a Packin pack to bytes like so:

val pack = PackinResourcePack.create(/*...*/)
val bytes: pack.createZip() // (ByteArray)

You can then hash and send this byte array to clients!

Where do my resources come from?

Resources are loaded from data packs(!?).

You can either

• Directly place resources in your src/main/resources
• Load built-in data packs to organise different sets of assets (Fabric API's ResourceManagerHelper#registerBuiltinResourcePack)
• Load packs through the world datapacks folder

File Structure

Resources are nested in a packin_resources folder. This comes just after the namespace, to prevent resources being loaded as other resource types by default.

For example:

• mod_id:sounds/example_sound.ogg is stored in data/mod_id/packin_resources/sounds/example_sound.ogg
• mod_id:font/example_font.ttf is stored in data/mod_id/packin_resources/font/example_font.ttf

Providers

Resource providers are how data is added to a Packin pack. You can view all available providers here.

Font Example

Here's an example of adding ChevyRay's Pinch font to a resource pack, an extension of the 'latin small capital' characters from the default Minecraft font.

PackinResourcePack.create(PackMetadata("Test Title", Text.literal("Test description"))) {
    addProvider(
        FontProvider(
            Identifier.of("mod_id", "pinch"), // assets/mod_id/fonts/pinch.ttf
            7.0f,                             // the size of the font
            4.0f,                             // the oversample of the font, the resolution to render at
        )
    )
}

You can now export the pack and the font will be included! For more info on the size and oversample values, see the Minecraft wiki here.

Shifts

You can provide a range of shifts for the font provider to generate also. The recommended way to achieve this is through FontShiftHandler, however it is possible to pass a plain list of Vector2fs to the end of the FontProvider constructor.

A font shift handler is a utility class that can be used to generate and reference shifted fonts. As each shifted font has a different ID, it can be difficult to trace them back to their original font (for width calculation, as an example).

Font shift handlers map shifted font ids back to their original id.

Horizontal font shifts are more dynamically handled by something like Amber's Negative Space font, so Packin does not provide a built-in way to generate those.

We do provide a vertical font shift handler. This can be created by providing a collection of ShiftRange objects, which can define a collection of shifts in a number of ways (see here for all shift range types).

Here's an example of adding the Pinch font with vertical shifts at exactly 5 and between 20 and 30.

val fontId = Identifier.of("mod_id", "pinch")

val fontShiftHandler = FontShiftHandler.createVertical(fontId,
    ConstantShiftRange(5.0f),      // exactly 5
    PrecisionShiftRange(20..30),   // 20,21,22,...,28,29,30
)

// the handler is passed into the provider, and the provider handles the generation
FontProvider(Identifier.of(fontId, 7.0f, 4.0f, fontShiftHandler)

Language Example

Language providers can be used to add language strings.

LanguageProvider("en_us") {
    this["my.language.string"] = "My Language String"
}

Model Textures Example

Model texture providers provide ONLY the textures of models that are given to them. If a texture in the minecraft namespace is found, it will NOT be provided, so ensure you use your own namespace for your textures.

All associated mcmeta files will also be collected.

ModelTextureProvider(
    Identifier.of("mod_id", "folder/my_model"), // assets/mod_id/models/folder/my_model.json
)

Sounds Example

Sound providers can be used to add sounds.

SoundProvider(
    Identifier.of("mod_id", "folder/my_sound"), // assets/mod_id/sounds/folder/my_sound.ogg
)

A sounds.json for all namespaces referenced will also be generated. Sounds can be referenced in-game by the identifier you provided. This means that Packin sounds break the convention of mod_id:folder.my_sound, instead being named like mod_id:folder/my_sound.

Warning

Ensure that any namespaces used are only referenced in a single sound provider, otherwise only the sounds within the last added sound provider will be included in the sounds.json file.

Unimplemented Sound Example

For sounds that will be implemented in the future, but you still want to reference in development, you can provide an unimplemented sound. This sound will be substituted in place of any sound file that cannot be found by the resource collector.

SoundProvider(
    Identifier.of("mod_id", "folder/my_sound"),
    unimplementedSound = Identifier.of("mod_id", "unimplemented"),
)

Warning

unimplementedSound = is very important, otherwise the sound will just be loaded as part of the list of sounds.

Sound Removal Example

The sound removal provider can be used to remove vanilla sounds from the pack. These are sound events, not ogg files.

VanillaSoundRemovalProvider(
    "block.stone.break",
    "block.stone.fall",
)

Direct Resources Example

A direct resource provider can be used to collect files directly from your source.

Note

Building a direct resource provider is a bit complicated and will likely be changed in the future.

Copy an entire registered pack

This will copy an entire pack registered through src/main/resources/resourcepacks.

DirectResourceProvider(packId = "mod_id:pack_id")

Copy a subfolder

Let's copy all vanilla texture overrides we've given in any pack we've loaded:

DirectResourceProvider(Identifier.DEFAULT_NAMESPACE, "textures/"), // DEFAULT_NAMESPACE = "minecraft"

How about our own texture and model assets:

DirectResourceProvider("mod_id", "textures/", "models/")

Or a specific one of our files:

DirectResourceProvider("mod_id", "folder/our_license.txt")