Getting Started

This guide builds the common application flow: install the core and a backend, create defaults, load a file, merge missing defaults, apply runtime overrides, read typed values, and save the document.

Add Dependencies

dependencies {
  implementation(platform("net.pistonmaster:pistonconfig-bom:0.1.0-SNAPSHOT"))
  implementation("net.pistonmaster:pistonconfig-core")
  implementation("net.pistonmaster:pistonconfig-yaml")
  implementation("net.pistonmaster:pistonconfig-env")
}

Use installation for Maven, GitHub Packages, and non-BOM examples.

Create Defaults

Defaults are just normal documents. That keeps manual defaults, annotation-generated defaults, static-field defaults, and resource-loaded defaults compatible with the same merge API.

var defaults = ConfigDocument.empty()
  .set("server.host", "0.0.0.0")
  .set("server.port", 25565)
  .set("server.online-mode", true);

defaults.root()
  .getOrCreate(ConfigPath.parse("server.port"))
  .setComment(ConfigComment.builder()
    .addLeading(ConfigCommentLine.builder()
      .text("Port used by the public listener.")
      .type(ConfigCommentType.BLOCK)
      .marker(ConfigCommentMarker.HASH)
      .build())
    .build());

Load the User File

var path = Path.of("config.yml");
var loader = YamlConfigFormat.INSTANCE.loader();

var document = Files.exists(path)
  ? ConfigLoaders.load(path, loader)
  : ConfigDocument.empty();

ConfigLoaders handles UTF-8 readers and writers. Format modules provide the actual ConfigLoader.

Merge Missing Defaults

document.mergeDefaults(defaults, MergeOptions.conservative());

MergeOptions.conservative() adds missing defaults and refreshes comments from the defaults. It does not replace user values or remove unknown user keys.

Use merge defaults when you need exact-default behavior or list strategies.

Apply Deployment Overrides

EnvironmentOverrides.system("myapp").applyTo(document);

With the myapp prefix:

Apply overrides after merging defaults and migrations so deployment values win.

Read Values

int port = document.find("server.port")
  .flatMap(ConfigNode::asInt)
  .orElse(25565);

String host = document.find("server.host")
  .flatMap(ConfigNode::asString)
  .orElse("0.0.0.0");

Accessors return Optional because files are external input. Decode near the boundary where you can choose a fallback or report an error.

Save the Result

ConfigLoaders.save(path, loader, document);

The backend writes the source detail it can represent. For example, YAML can write inline comments, scalar styles, anchors, and collection styles; properties files keep a flatter model and layout attributes.

Next Choices