Engine options and JVM properties

Engine options configure Anvil itself. A managed server's JVM arguments configure that child process separately. For a JUnit run, put additional engine properties on the test JVM:

import me.whereareiam.anvil.integration.junit.gradle.AnvilTest

tasks.withType<AnvilTest>().configureEach {
	systemProperty("anvil.stopTimeout", "PT30S")
	systemProperty("anvil.java.download", "false")
}

This fragment belongs in the consumer build.gradle.kts after applying the JUnit plugin. It configures anvilTest and the task of every suite. It allows thirty seconds for graceful process shutdown and requires each process's planned Java installation to be available without a download. It does not change anvilRun.

Which entry point reads what?

Do not assume ./gradlew -Danvil.someProperty=... anvilTest forwards an arbitrary property into the forked test JVM. Use the Test.systemProperty configuration above. To decode properties in an embedding application, call EngineProperties.from(properties) or EngineProperties.fromSystemProperties() from me.whereareiam.anvil.engine.config explicitly.

Properties

PT30S means thirty seconds. Invalid booleans, nonpositive limits, invalid timeout values, and malformed archive checksums fail during decoding. Archive URI and checksum must be supplied together. Configure at most one explicit source: home, executable, or archive.

anvil.console.colors accepts true or false. IDE sessions enable it unless the prepared launch properties explicitly set it to false. Direct embedding uses EngineOptions.builder().consoleColors(true). Platform providers translate the request into their own console options; explicit JVM arguments on a server or proxy take precedence over those defaults.

Java settings describe the engine default. A process declaration overrides the scenario's Java selection, and the scenario overrides the engine default. An engine Java version applies to every process without its own requirement; planning refuses it for a process whose platform version does not accept it, so give that process its own JavaRequirement. Execution selection can also be overridden by the scenario. Docker images need provider-specific configuration; there is no anvil.docker.image property. See Execution providers.

Lifetimes and limits

EngineOptions.processTimeouts supplies startup and shutdown defaults. A scenario's processTimeouts can override either member independently. Startup limits the time for each process to become ready; shutdown is the grace period before forced termination. Capability waits keep their own deadlines.

EngineOptions.processScheduling groups preparation/start parallelism and the declared heap allowance for simultaneous starts. An omitted value is selected from host capacity. These limits apply within each scenario preparation or bulk-start operation; they are not an aggregate cap across all active scenarios. A process whose declared heap exceeds the allowance starts alone. Already-running processes are not counted against this startup allowance. Scenarios do not override scheduling limits. Artifact download concurrency remains a separate engine option.

processors and priority in the same group limit how much of the machine the launched processes take. A server sizes its thread pools from the processors it sees, so a few servers starting at once ask for far more than a machine has; processors passes each process -XX:ActiveProcessorCount, and a process's own JVM argument of that name wins. priority set to low starts processes through nice, so they yield to other work on the machine while scenarios run. Local execution supports it on Linux and macOS and refuses it on Windows; Docker execution refuses it.

For direct embedding, configure the groups explicitly:

import me.whereareiam.anvil.api.model.EngineOptions;
import me.whereareiam.anvil.api.model.process.lifecycle.ProcessScheduling;
import me.whereareiam.anvil.api.model.process.lifecycle.ProcessTimeouts;
import java.time.Duration;

EngineOptions options = EngineOptions.builder()
		.executionProviderId("local")
		.processTimeouts(ProcessTimeouts.builder()
				.startup(Duration.ofMinutes(2))
				.shutdown(Duration.ofSeconds(15))
				.build())
		.processScheduling(ProcessScheduling.builder()
				.parallelism(2)
				.startupMemoryMegabytes(4096)
				.build())
		.build();

keepFailedWorkspaces applies when the scenario lifecycle is marked unsuccessful, including startup and restart failures. The JUnit integration also passes a failed test outcome to scenario finalization. See Cleanup diagnostics for inspecting retained workspaces.

The shared cache can include private authentication state. Selectively cache verified artifacts in CI; never upload the protocol library's private account store or tokens. Offline mode uses previously acquired artifacts and metadata; it is not a machine-wide network firewall for plugins or game sessions.