Artifacts

Anvil retains acquired software so repeated runs can reuse their inputs. Configure its location through the cache overview, and keep the same root when preparing and later running an environment offline.

What is retained

The acquisition cache stores downloaded artifact files and resolution metadata. A platform provider can first read cached build metadata, then locate and verify the selected executable. Java provisioning also retains downloaded archives and prepared installations. The MCProtocolLib library keeps the runtime JARs of each release its players use under protocol/mcprotocol/<release> in the cache root, checked against the release's pins.

When an expected SHA-256 is supplied, Anvil verifies cached or newly downloaded artifact bytes against it. A missing or invalid cached artifact needs acquisition again; offline mode cannot repair it. Resolution metadata matters too: possessing a JAR alone may not be enough to resolve its remote build selector without network access. Metadata that does not answer the request, such as a Java package search that found nothing, is not retained: the next run asks again instead of failing on a stored empty answer.

These inputs can remain outside the process workspace. Cache reuse does not mean that every executable is copied into the workspace or that your plugin's generated data is retained automatically.

Prepare an offline test run

First run the intended environment with normal online settings and the same cache root, or supply its required local artifacts and Java installations. Then add this fragment to the consumer build.gradle.kts after applying the JUnit plugin:

import org.gradle.api.tasks.testing.Test

tasks.named<Test>("anvilTest") {
	systemProperty("anvil.offline", "true")
	systemProperty("anvil.refresh", "false")
	systemProperty("anvil.java.download", "false")
}

Run the prepared test with ./gradlew anvilTest --tests 'com.example.test.PlayerJoinTest', replacing the class name with your own. The settings apply to the Anvil test JVM. They do not configure the managed server JVM or the foreground anvilRun task. For other entry points, use the engine options reference.

The example requires already available software. If an acquisition input or its metadata is missing, Anvil reports that failure instead of downloading it. The Java flag additionally requires a suitable local or prepared Java installation; it does not merely toggle distribution downloads.

Choose the acquisition policy

• anvil.offline=true makes Anvil's acquisition services use retained artifacts and metadata.
• anvil.refresh=true asks resolution to refresh moving metadata or selections. It does not replace an explicit build number or checksum in your declaration.
• anvil.java.download=false disables provisioning missing Java installations. It does not disable platform downloads, and it is not required merely to reuse a cache.

Offline and refresh cannot both be enabled; Anvil rejects that combination when creating the artifact store. Offline acquisition is not a firewall for plugins or game sessions. Gradle dependency resolution is also separate: Anvil's flag does not stop Gradle from resolving build plugins or Maven dependencies. A named artifact has already been supplied as a local file by Gradle or the embedding application. AssetSource accepts a local path or such a registered artifact, not an arbitrary download URL.

Offline mode does not disable snapshot restores or saves; those use the selected workspace cache policy.