Skip to content

resource-pack-management.md

Latest commit

 

History

History
265 lines (220 loc) · 16.7 KB

resource-pack-management.md

File metadata and controls

265 lines (220 loc) · 16.7 KB

Resource Pack Management

This document explains Gamemode 4's Resource Pack management tools, which use custom beet plugins to remove lots of redundancy in the source code.

Table of Contents

Getting Started

Just like how data pack resources are stored in a data directory, resource pack assets are stored in an assets directory for each module, and follow the same structure as an ordinary minecraft resource pack.

Beet must be configured to load these files by adding to the beet.yaml:

resource_pack:
  load: .

Building the Resource Pack

When building a single or list of modules with beet dev, a combined resource pack containing assets for the specified modules is built in the out directory. If the beet --link option is set, the pack will also be sent to Minecraft's resource packs folder.

Since Gamemode 4 publishes a single resource pack that contains textures for all our modules combined, building a complete copy of the resource pack locally requires building every module. Since this often takes a while, developers are encouraged to only build the packs they are currently working on to save time.

Custom Model Data

String references can be used instead of hard-to-remember integers when dealing with custom model data. After configuring the custom model data values your data pack will use a mecha plugin will auto-assign the unique integer values and substitute them into the data pack output by the beet build process.

model_data:
  - item: rabbit_hide
    reference: gm4_bat_grenades:item/bat_leather
    template: generated
give @s rabbit_hide[custom_model_data="gm4_bat_grenades:item/bat_leather"]
summon item ~ ~ ~ {Item:{id:"rabbit_hide",count:1,components:{"minecraft:custom_model_data":"item/bat_leather"}}}

For full details about the model_data config see model_data Config

Language Support

Support for additional languages is managed through babelbox, which uses a spreadsheet of translation keys and their corresponding values in multiple languages, which can be located at either gm4_module_name/translations.csv or gm4_module_name/assets/translations.csv. Individual language .json files are then generated by the build process.

English (en_us) translation values are required for every translation key used in the pack. Other languages are optional and entries can be left empty if no translation is available.

Example translations.csv:

key,en_us,de_de
item.gm4.bat_leather,Bat Leather,Fledermausleder
text.gm4.bat_leather.1,"Would make for a very strange,","Würde eine ziemlich merkwürde,"
text.gm4.bat_leather.2,very tiny jacket,ziemlich kleine Jacke ergeben

Which if opened as a spreadsheet like excel or libreoffice is structured as

key en_us de_de
item.gm4.bat_leather Bat Leather Fledermausleder
text.gm4.bat_leather.1 Would make for a very strange, Würde eine ziemlich merkwürde,
text.gm4.bat_leather.2 very tiny jacket ziemlich kleine Jacke ergeben

English translations can also be auto-filled from text component fallbacks in other project files by setting babelbox_backfill to True in the build options. This is especially useful when adding guidebook translations, normally defined in guidebook.json to the translations.csv.

beet -s meta.gm4.babelbox_backfill=True dev bat_grenades

Model Templates

Templates allow for easy generation of common model file structures. Uses the textures field (or its default value of reference) to find the texture file(s). Available default templates are:

  • custom: does not generate a model file(s).
  • generated: generates a model of the minecraft:item/generated parent. Often used to turn a single texture image into a flat held item in-game. e.g.
- item: firework_star
  reference: item/everstone
  template: generated
  • generated_overlay: generates a model with two layers, where the second texture is the same as the first, followed by _overlay. Intended for potions and other similar items
  • handheld: generates a mode of the minecraft:item/handheld parent. Used for turning single textures into a tool item in-game.
  • vanilla: use the vanilla item model. Often used when no textures exist yet but a CMD value should still be reserved.
  • block: generates a model of the minecraft:block/cube parent. Textures are specified in the order [top, bottom, front, side], or by mapping to their names. e.g.
- item: piston
  template: block
  reference: block/forming_press
  textures:
      front: block/forming_press_side
      side: block/forming_press_side
      top: block/forming_press_top_out
      bottom: block/forming_press_bottom
 - item: enchanting_table
   template: block
   reference: block/enchantment_extractor
   textures:
      - block/enchantment_extractor_top_out
      - minecraft:block/furnace_top
      - block/enchantment_extractor_side
      - block/enchantment_extractor_side
  • advancement: generates a model to be used in an advancement icon. This is a different CMD from the actual item to facilitate retexturing just the advancement and not the whole item. Redirects to a specified forward model file. This template ignores the model config field.
- item: gunpowder
  reference: gui/advancement/bat_grenades
  template:
    name: advancement
    forward: item/bat_leather
  • legacy_machine_block: generates a model following the block template, but with a set of transformations that scale and translate the model to match the position/scale of the "block on the head of a small armor stand" that is used in so many of our machine blocks.

Individual modules can also create their own templates (see here) that may be imported and used. The most common of these is metallurgy's shamir, which generates models for a shamir band, and tool/armor models with the shamir applied. Has the following sub-config:

  • textures_path: directory of textures to use when the shamir is on a tool. Textures from metallurgy will be substituted for any missing textures. Unless the shamir has unique textures, its recommended to just use the metallurgy folder corresponding to the metal type.
  • metal: which metal this shamir is This template also overrides the item field of the config to allow more broad item groups, such as armor, tools, weapons, axes, helmets ect...
- item: swords
    reference: shamir/corripio
    template:
      name: shamir
      metal: bismuth
      textures_path: gm4_metallurgy:item/shamir/bismuth

Model Transforms

The transforms field of model config is used to apply transformations (rotation/translation/scale) to a template-generated (or custom provided) model. The plugin only defines one available transform:

  • item_display. This transform does the convenience calculations for an item model that will be displayed by an item display entity. By first setting up the display entity without the resource pack, and providing the entite's display parameters, the specified model will be modified to a 1-block scale, aligned with the block grid. Accepts the required parameters origin, scale, and the optional parameters translation=[0,0,0], rotation=[0,0,0], display=head
- item: glass
  template: custom
  reference: block/liquid_tank
  transforms:
    - name: item_display
      origin: [0.5,0.9,0.5]
      scale: [0.438,0.438,0.438]
      translation: [0,0,0]
      display: head

Advanced Usage

The following sections of this guide describes more advanced features of the resource pack plugin, that may be required for developers wishing to add additional templates or interact with special fonts.

model_data Config

All custom model data and model template config information is stored either in meta.gm4.model_data field of beet.yaml, or in the model_data field of the separate config file assets/model_data.yaml. This is a list of compounds, each of which accepts the following fields:

  • item: (required) item name, or list of item names this custom model data will be applied to.
  • reference: (required) the unique string reference to be used in source files e.g. item/bat_leather. If no namespace is specified, the module's namespace will be assumed. It is recommended to format references according to the type of item it applies to. e.g. item/..., block/..., gui/... ect, and especially recommended to use the model/texture file path where possible.
  • model: (optional) the model file(s) to display on items with this custom model data. If not specified, will default to the same value as reference. Accepts a string or list of strings, one for each item present in item. May be formatted as a dictionary mapping items to models e.g.
item: [apple, potato]
model:
  apple: item/my_model_apple
  potato: item/my_model_potato

More complex model styles, like for items with multiple vanilla models (e.g. elytra & broken elytra, clock ect) are handled through a special-case syntax. Currently only broken elytra are supported, so packs utlizing conditions in item model definitions will need to provide handlers.

item: elytra
model:
  type: condition_broken
  unbroken: item/elytra/captains_wings
  broken: item/elytra/broken_captains_wings

Items who have multiple vanilla models, like clocks, who do not utilize special-case providers in the model config will have the same provided model file applied to all variants.

  • template (optional), a model-file generating template to apply. Accepts a string name of a template, or a compound containing template configuration values. Defaults to custom, which generates no Model files. See here for details on available templates.
  • transforms (optional), a list of model transforms to apply. Accepts a compound of configuration data. See here for details on available transforms.
  • textures (optional), a string, list of strings, or mapping of texture files to supply to the template.
  • broadcast (optional*), a list of sub-configs which will inherit the current config values. This reduces redundancy when defining many similar references. Due to the inheritance, each config need not contain every required field, so long as after the broadcast is carried out all required fields have a value. e.g.
model_data:
  - item: player_head
    template: generated
    broadcast:
      - textures: item/band/mundane_band
        reference: item/mundane_band
      - reference: item/lump/baryte
      - reference: item/lump/bauxite
      - reference: item/lump/bismutite
      - reference: item/lump/thorianite

gui_fonts Config

Custom textured GUIs using fonts can easily be setup using the meta.gm4.gui_fonts entry of beet.yaml or the gui_fonts entry of model_data.yaml. These will create a translation that displays a given image texture inside a container, like a dropper or hopper. Empty images of the correct size are available in the base to use as a starting point for custom GUIs.

Available options are:

  • translation: the translation key that will become the texture. Recommended to follow the format gui.gm4.my_container.
  • texture: the image texture to display
  • container: the type of container the gui will display inside. Currently accepts dropper, and hopper. Additional containers formats can be added by extending the ContainerGuiOptions class.
gui_fonts:
  - translation: gui.gm4.auto_crafter
    container: dropper
    texture: gm4:gui/container/empty_dropper

translation_linter_ignores Config

Individual translation keys can be excluded from the mecha linting process by adding them to the meta.gm4.translation_linter_ignores config in beet.yaml. This should only be used in unusual situations where translations are being used in other ways than displaying text.

Custom Model Data Allocations

Sometimes it is desirable to put all the custom model data integer values near each-other for organizational purposes. There is a manual config available in the modeldata_registry.json file, which lets sets up additional ranges for a module (or glob of modules) that can be auto assigned by the resource pack plugin.

    "gm4_orb_of_ankou": [
      200,
      299
    ],
    "*_shamir": [
      100,
      199
    ],

Extending TemplateOptions

Individual modules may create and configure their own model templates by extending the TemplateOptions class in a beet plugin. The subclass must define its name as a class variable, and a process method which creates the models, mounts them to the pack, and returns them in a list. Additional instance attributes can be defined, and their values will be filled by any values provided in the model_data config under template.

Has the following class attributes and methods that may be overridden:

Properties

  • name: (required) A unique string that identifies this template and is set in the template field of model_data.
  • default_transforms: (optional) A list of TransformOptions instances. Used to give a template transformations that are applied by default, such as for a series of custom weapons with special offsets in the hand slots.
  • texture_map: (optional) A list of strings that defines the ordering of textures when configured in list form. Allows the model creation to access config.textures by key instead of index, which may be more robust.

Methods

  • process(self, config: ModelData, models_container: NamespaceProxy[Model]) -> list[Model]:: Creates the required model(s) instances defined by the config, mounts them to the pack models_container at the proper location, and returns the models for further transformation processing.
  • add_namespace(self, namespace: str): Adds the pack namespace to any additional attributes added by this subclass, and returns a new instance of this TemplateOptions with that namespace applied.
  • mutate_config(self, config: ModelData): Allows this template to mutate/mangle root level fields of the parent ModelData, such as model or reference. Used for unusual models like metallurgy's shamir that allow item groups in the item field for convenience.

Extending TransformOptions

Individual modules may create their own transformations by extending the TransformOptions class in a beet plugin. The subclass must define its name as a class variable, an apply_transform method that modifies a given model with the appropriate offsets, and any additional instance attributes required for that particular transform.

Methods

  • apply_transform(self, model: Model) -> None: Modifies the given Model instance in-place with the desired display offset settings.

Extending ContainerGuiOptions

Individual modules may add containers to gui_fonts as needed by extending the ContainerGuiOptions class in a beet plugin. The subclass is responsible for requisitioning unicode characters from a central counter and returning the appropriate translation value and font providers.

The inherited method next_unicode(counter_cache: Cache) can be used to easily get a unique unicode character.

Additionally, there are two extendable subclasses already available for containers whose name is centered (like a dropper) and right-aligned (like a hopper). They are CenteredContainerGui and RightAlignedGui respectively.

Methods

  • process(self, config: GuiFont, counter_cache: Cache) -> tuple[str, list[dict[str, Any]]]: Requisitions unique characters and returns the translation value (usually made of these characters), and a list of font providers, which usually reference config.texture.

Extending ItemModelOptions

Individual modules may add additional handlers for special-case item model definitions by extending ItemModelOptions in a beet plugin. This subclass defines the additional config fields and a method that generates the model compound used in the item model definition.

Methods

  • 'generate_json(self) -> dict[str,Any]`: Returns the model object used in the item model defintion. e.g. {"type": "minecraft:condition"...}