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, fills missing comments, and repairs values whose node kind no longer matches the defaults. It does not replace compatible 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