Skip to content

Configuration

Jump to bottom Edit New page
Matej Kormuth edited this page Jan 8, 2016 · 4 revisions

Here you can read about configuration files of rpbuild. But be sure to check out example config after you finish reading, it may really help you to better understand, how rpbuild configs work!

HOCON

Rpbuild 2 uses HOCON (Human-Optimized Config Object Notation) for it's build configuration. It's simpler and less verbose than XML.

You can find more about HOCON here: https://github.com/typesafehub/config/blob/master/HOCON.md

Build file

You can use any name for build file, but standard and default name is rpbuild.conf. You can then invoke build by running rpbuild instead of rpbuild build your_name.conf.

Structure

The whole configuration is wrapped by project object. In the project object, you can configure the name, encoding, compression settings, git integration, repositories, properties, and build tasks.

project {
   name: "My resource pack"
   encoding: "UTF-8"
   source: "."
   target: "latest.zip"

   ...
}

Git integration

You can integrate Git to your project build by adding git object to project object.

project {
  ...

  git {
    # Whether to pull changes from Git before building the resource pack.
    pull: true
    # Branch to use for build.
    branch: "develop3"
    # Whether we should exclude .git folders from final zip (recommended true).
    ignoreGitFolders: true
    # Git url.
    url: "https://github.com/pexelnet/starvingrp.git"
  }
  ...
}

Compression settings

Compression settings allows you to change compression type (at this moment only ZIP is supproted) and it's settings. We however recommend you to use the highest level of compression 9 to get the smallest possible size.

project {
  ...

  # Compression settings.
  compress {
    # Zip compression level.
    level: 9
  }

  ...
}

Repositories

If you use custom plugins that are not bundled or in central repository, you can add a custom plugin repository by creating an repository object in repositories object.

To learn more about custom plugins or repositories, please read [Writing plugins] and [Plugin repositories].

project {
  ...

  # Repositories to search for plugins.
  repositories {
    central {
      url: "https://matejkormuth.eu/rpbuild/repo/"
    }

    # Name / ID of the custom repository.
    starving {
      # Url of the custom repository.
      url: "http://starving.eu/rpbuild/"
    }
  }

  ...
}

Properties

This is just a standardized place for all your substitution properties. You can however declare any properties anywhere.

Build tasks definition

This is the most important place in your configuration. Here you can configure, how will be your resource pack built. We provide you with some basic example configurations, but you can define your own build tasks and settings.

The build definition starts with the root build section called build. This root section maps to the source folder specified in your configuration (it defaults to current directory, thus the directory of resource pack).

All sub-sections are defined with names of folder, that you want to run any tasks on.

project {
  ...

  # Build process specification.
  build {
    # Global exclude rules.
    exclude: ["rpbuild.xml" "*.jar" "*.zip" "*.bat" "*.sh" "*.php" "*.log" ".gitkeep" "*.db" ".git" "**.git*"]

    ...
  }
  ...
}

Each build section can define it's excludes, plugins and sub-build sections.

Important thing: all sub-build sections inherit all parent excludes and plugins!

Excludes

Excludes are written as string list in HOCON. They can be defined in any build section and they are written in GLOB form. You can read more about glob here: https://en.wikipedia.org/wiki/Glob_(programming) but we provide you with some examples.

To exclude a specific file in selected folder use: */file.ext.

To exclude a specific file in any descendant folder use: **/file.ext.

To exclude specified type of file, use: **/.bdc3D

...

      # Select subdirectory 'models'.
      "models" {
        # Local (folder and subfolder) exclude rules.
        exclude: ["**/.bdc3D"]

        plugins {
        }
      }

...

Plugin declarations

Plugin declarations are written in object plugins in any build section. If you want to use default configuration, just create a object with name of plugin and parentheses {}.

If the plugin supports configuration, write configuration values inside parentheses.

By default, you don't have to specify version of the plugin. Rpbuild will try it's best to use the latest version of specified plugin. If you really need to use specific version of plugin, write it's name in form of plugin-name:version.

...

    # Select directory.
    "assets/minecraft" {
      # Plugins to run on all files in this directory.
      # If specified plugin does not compile files, it will invoke generate task instead.
      plugins {
        # Generate pack.mcmeta file from information about build.
        rpbuild-packmcmeta-plugin {
            # Override default generated description.
            description: "Yey description!"
        }

        # Minify all JSON files in this directory and subdrectories.
        rpbuild-jsonminify-plugin {}
      }

...

Example build configuration

Use this configuration as starting point, and modify it to your needs.

# Root of project.
project {

  # Name of project.
  name: "Starving 3.0 RP"
  # Encoding used to process text files.
  encoding: "UTF-8"

  # Source directory.
  source: "."
  # Target zip file.
  target: "../latest.zip"

  # Git related settings.
  git {
    # Whether to pull changes from Git before building the resource pack.
    pull: true
    # Branch to use for build.
    branch: "develop3"
    # Whether we should exclude .git folders from final zip (recommended true).
    ignoreGitFolders: true
    # Git url.
    url: "https://github.com/pexelnet/starvingrp.git"
  }

  # Compression settings.
  compress {
    # Zip compression level.
    level: 9
  }

  # Repositories to search for plugins.
  repositories {
    central {
      url: "https://matejkormuth.eu/rpbuild/repo/"
    }

    # Name / ID of the custom plugin repository.
    starving {
      # Url of the repository.
      url: "http://starving.eu/rpbuild/"
    }
  }

  # Configurable arbitrary properties.
  properties {
    # Size of block pack.
    blocksSize: 128
    # Size of item in resource pack.
    itemsSize: 256
  }

  # Build process specification.
  build {
    # Global exclude rules.
    exclude: ["rpbuild.xml" "*.jar" "*.zip" "*.bat" "*.sh" "*.php" "*.log" ".gitkeep" "*.db" ".git" "**.git*"]

    # Select directory.
    "assets/minecraft" {
      # Plugins to run on all files in this directory.
      # If specified plugin does not compile files, it will invoke generate task instead.
      plugins {
        # Generate pack.mcmeta file from information about build.
        rpbuild-packmcmeta-plugin {}

        # Minify all JSON files in this directory and subdrectories.
        rpbuild-jsonminify-plugin {}
      }

      # Select subdirectory 'sounds'.
      "sounds" {
        plugins {
          # Generate sounds.json from files in sounds directory.
          starving-soundsjson-plugin {
            # Threshold of sound length for streaming: true.
            streamingThreshold: 2500

            # File contaning category mapping for all sounds.
            categories: "categories.json"
          }

          # Generate more variations of specific sound files.
          starving-soundprocessing-plugin {
            #########################
            #       CONFIGURE!      #
            #########################
          }
        }
      }

      # Select subdirectory 'textures'.
      "textures" {
        plugins {

          # Run optipng using optipng plugin.
          rpbuild-optipng-plugin {
            # Optimization level (0-7) default 2.
            level: 7

            # Max amount of images that will be processed in parallel.
            instances: 4
          }

          # PngQuant plugin is not yet implemented.
          # rpbuild-pngquant-plugin {}

          # Mangle texture names.
          # rpbuild-mangle-plugin {
          #  # Mangle plugin mode.
          #  mode: "textures"
          #  # Name of source map file.
          #  sourcemap: "textures.map"
          #  # Multithreaded?
          #  multithreaded: true
          # }
        }

        # Select subdirectory 'blocks'.
        "blocks" {
          plugins {
            # Downscale all textures.
            rpbuild-downscale-plugin {
              # Max resolution of texture in pixels.
              maxResolution: ${project.properties.blocksSize}
              # Type of interpolation to use (nearest, bilinear, bicubic).
              interpolation: "bicubic"
            }
          }
        }

        # Select subdirectory 'items'.
        "items" {
          plugins {
            # Downscale all textures.
            rpbuild-downscale-plugin {
              # Max resolution of texture in pixels.
              maxResolution: ${project.properties.itemsSize}
              # Type of interpolation to use (nearest, bilinear, bicubic).
              interpolation: "bicubic"
            }
          }
        }
      }

      # Select subdirectory 'models'.
      "models" {
        # Local (folder and subfolder) exclude rules.
        exclude: ["*.bdc3D"]

        plugins {
          # Mangle model names.
          # rpbuild-mangle-plugin {
          #  # Mangle plugin mode.
          #  mode: "models"
          #  # Name of source map file.
          #  sourcemap: "models.map"
          # }
        }

        # Select subdirectory 'blocks'.
        "blocks" {
          plugins {
            # Fix missing 'particle' texture on models.
            starving-fixparticle-plugin {}
          }
        }
      }

      # Select subdirectory 'blockstates'.
      "blockstates" {
        plugins {

        }
      }
    }
  }
}

Proceed with learing how to configure bundled plugins or reading about plugin respositories.

Thank you for using rpbuild 2!

logo

Contents:

Clone this wiki locally