Repository navigation
Resource packs
Use DataPack for server data and AssetPack for client assets. Both registrars are available in common code on Fabric and NeoForge. A registered pack has its own selection entry and can contain bundled files, generated files, or both.
The Java API is organized under it.crystalnest.cobweb.api.pack.
| Package | Types and responsibilities |
|---|---|
pack |
DataPack, AssetPack, and ResourcePack for pack registration. |
pack.generation |
Callback registration, context, typed data and asset resource views, and server publication output. |
pack.generation.input |
Input declarations and values captured at load start. |
pack.generation.output |
Output declarations, native asset resource kinds, resource lifetimes, and sound definitions. |
pack.generation.lifecycle |
Phases, stages, load kinds, and load outcomes. |
pack.dependency |
Pack and mod requirements and version constraints. |
pack.presentation |
Pack titles, descriptions, icons, and explicit refresh of the client pack editor. |
pack.query |
Pack identity, activation policy, selection and priority queries, and exports. |
pack.selection |
Internal client and server selection hooks. |
pack.command |
Internal client and server inspection export commands. |
pack.delivery |
Internal server asset delivery and hosting. |
Implementation helpers live beside the API for each feature. Treat types marked @ApiStatus.Internal as implementation details. Client-only entry points such as AssetResourceKinds, GenerationContext.assets(), and PackPresentations.refresh() require a client.
Put bundled files under the pack's root:
resources/
datapack/
extra_recipes/
pack.mcmeta
data/...
texturepack/
alternative_assets/
pack.mcmeta
assets/...
The identifier namespace is the owning mod ID, and its path is the pack directory below datapack/ or texturepack/.
These roots are fixed. Cobweb uses the native selection IDs mod/<mod_id>:datapack/<pack_path> and mod/<mod_id>:texturepack/<pack_path>, whether or not the pack has callbacks.
Register your packs during mod initialization:
import it.crystalnest.cobweb.api.pack.AssetPack;
import it.crystalnest.cobweb.api.pack.DataPack;
import it.crystalnest.cobweb.api.pack.query.PackActivation;
import net.minecraft.network.chat.Component;
import net.minecraft.resources.Identifier;
import net.minecraft.server.packs.repository.Pack;
DataPack.registrar(Identifier.fromNamespaceAndPath(Constants.MOD_ID, "extra_recipes"))
.activation(PackActivation.DEFAULT_ENABLED)
.register();
AssetPack.registrar(Identifier.fromNamespaceAndPath(Constants.MOD_ID, "alternative_assets"))
.title(Component.literal("Alternative assets"))
.position(Pack.Position.TOP)
.fixedPosition(false)
.register();register() installs and returns the pack. If you want to generate files, add callbacks to that pack during initialization.
| Registrar option | Default | Meaning |
|---|---|---|
title(Component) |
Generated translatable title | Display title; pass Component.literal(...) for literal text. |
title(String) |
Generated translatable title | Treats the string as a translation key, using Component.translatable(...). |
activation(PackActivation) |
DEFAULT_DISABLED |
Initial optional selection or required activation. |
position(Pack.Position) |
TOP |
Initial top/bottom placement, including automatic first-time enabling. |
fixedPosition(boolean) |
false |
Anchors the pack in the native top/bottom group in the selection UI. |
source(PackSource) |
BUILT_IN |
Native source label and behavior, independently of initial activation. |
The default title keys are datapack.<mod_id>.<pack_path> and texturepack.<mod_id>.<pack_path>.
For example, example:extra_recipes produces datapack.example.extra_recipes:
{
"datapack.example.extra_recipes": "Extra recipes",
"texturepack.example.alternative_assets": "Alternative assets"
}Supply a description and supported formats in pack.mcmeta or Java. Explicit description(Component) and formats(...) values replace the corresponding file fields. Use currentFormat() to declare the running game's format. pack.mcmeta can be omitted when Java supplies the required fields.
The bundled root can also provide pack.png, feature flags, filters, and overlay directories. Within one pack, generated files override bundled base files, then active overlays take precedence. Minecraft applies the same native priority between that pack and the rest of the selection. NeoForge's native conditional overlays remain available.
Metadata is read during repository discovery. Rejected metadata produces native diagnostics and the pack is omitted. Use ResourcePack.toPack() when integrating with code that needs a native Pack. It creates the same native representation and returns null if Minecraft rejects the metadata or the required pack section is missing.
| Activation | Behavior |
|---|---|
DEFAULT_DISABLED |
Optional and initially disabled. |
DEFAULT_ENABLED |
Optional and initially enabled. Users can disable it. |
ALWAYS_ACTIVE |
Required. Users cannot disable it, including through /datapack disable. |
Activation and position are independent: an always-active pack can still be moved, and an optional pack can have a fixed position. Fixed position means the top or bottom group, not an arbitrary numbered slot or a unique first/last position. Explicit data-pack ordering commands retain their native behavior.
Optional defaults apply when a pack is first encountered; later launches preserve the user's selection and order.
Changing an optional default does not override that choice. A pack changed from always active to optional remains enabled until the user disables it.
Data-pack selections are saved per world. Asset-pack selections are saved in client options. The client also records discovered Cobweb asset packs in data/cobweb_resource_packs.json so first-discovery defaults respect later user choices. If a client asset pack disappears from discovery and later returns, its declared default applies again.
Native feature-flag requirements and compatibility handling remain in effect.
Generated files become available at their native loading boundary. Changes to callback inputs can affect the next applicable native load or reload.
var generated = DataPack.registrar(Identifier.parse("example:generated"))
.description(Component.literal("Generated data"))
.currentFormat()
.activation(PackActivation.ALWAYS_ACTIVE)
.register();
generated.onGenerate(Inputs.NONE, Outputs.of(Output.TAGS), (context, output) -> {
output.tags(Registries.ITEM).add(
Identifier.parse("example:kindling"),
TagEntry.element(Identifier.parse("minecraft:stick"))
);
});Use output.registryEntries(definition).put(id, value) to produce an entry for a data-pack registry. For assets, putTranslations writes a complete language file. Raw text, JSON, binary streams, and codec-based writers let you submit other resources using their native paths. Call namespaces(...) on the registrar before generating into additional namespaces.
Use ResourceKind.json(directory, codec, lifetime, deadline) to reuse a custom JSON contract. Pass kind.output() to Outputs.of(...), submit definitions with output.put(kind, id, value), and read a winning definition with context.resources().get(kind, id).
On the client, AssetResourceKinds provides contracts for blockstates, item definitions, particles, atlases, and fonts. It can also submit a model produced by Minecraft's model generation API.
Use context.data() for native registry lookups, prepared tag membership, feature flags, structure NBT, and completed recipe definitions. Use context.assets() for typed asset reads such as sprites, sounds, and translations. Use context.resources() for general file lookups and resource stacks. A decoded sprite owns its native image and should be closed after use.
AssetResourceKinds.putSprite writes a PNG and its optional native animation metadata together. Replacing the sprite with a static one removes a previous helper-owned sidecar from this pack. A separately submitted raw sidecar retains its own precedence. Use putSound to include encoded Ogg audio and putSoundDefinition to contribute an event to the namespace's sounds.json. Each event is replaced as a complete definition, and different event names can be contributed independently.
Each phase runs Preparation, Generation, and Transformation in that order. Use onPrepare, onGenerate, and onTransform to select a stage. The phase can be supplied directly or inferred from declared inputs and outputs. Use onStage when Cobweb can also infer the stage. A synchronous callback completes on return. The Async methods wait for the returned CompletionStage<Void> before advancing beyond that stage.
| Phase | Runs on | Boundary |
|---|---|---|
DATA_RESOURCES |
Server full load and reload | Before native tag preparation |
STATIC_TAGS_READY |
Server full load | After static tag preparation and before world registries |
WORLD_REGISTRIES_READY |
Server full load | After world registries and before dimension registries |
WORLD_CONTEXT_READY |
Server full load and reload | Before reloadable registries, with the world context available |
RELOADABLE_REGISTRIES_READY |
Server full load and reload | After reloadable registries and before ordinary reload listeners |
CLIENT_RESOURCES |
Client initial load and reload | Before native client resource preparation |
context.resources() reads the combined native resource view and completed generation visible to the callback. before and after order generation between packs that have callbacks. The native selected order determines which pack wins a file conflict. If two callbacks in one pack submit the same complete file, the last submission wins. Use explicit tag additions to aggregate tag members.
Java callbacks and JSON rules in the same phase and stage share the first-read contents of each resource version they resolve in common. Each open gets its own stream over those bytes. A later stage can capture the source again. A lookup that only checks for a file does not read its contents.
Full-load output remains available for the lifetime of that world. Deselecting an optional pack removes its files from resource resolution. Reselecting it during the same world restores its original full-load files.
A selected pack from Minecraft's local resource-pack or world data-pack folder can generate files without a mod of its own. Add cobweb/rules.json at the root of the folder or ZIP, alongside pack.mcmeta. A pack registered in Java can bundle the same file and use it alongside its callbacks.
{
"format": 1,
"assets": {
"rules": [
{
"op": "copy",
"stage": "generation",
"from": "minecraft:models/block/stone.json",
"to": "example:models/block/stone_variant.json"
},
{
"op": "patch_json",
"from": "example:models/block/stone_variant.json",
"to": "example:models/block/stone_variant.json",
"edits": [
{"op": "add", "path": "/textures/all", "value": "minecraft:block/smooth_stone"}
]
}
]
},
"data": {
"after": ["example:base"],
"rules": [
{
"op": "patch_json",
"from": "minecraft:recipe/stone_slab.json",
"to": "minecraft:recipe/stone_slab.json",
"edits": [
{"op": "replace", "path": "/result/count", "value": 12}
]
}
]
}
}Use namespaced file paths relative to assets or data, including the extension. copy copies the file bytes. patch_json applies add, replace, and remove edits in order using JSON Pointer paths. The empty pointer refers to the whole document, and - appends to an array for add. A missing input fails the load by default. Set "on_missing": "skip" to skip the whole rule if any input is absent. Invalid input or edits still fail the load.
Rules default to transformation in the latest phase that can supply their destination. Use stage to choose preparation, generation, or transformation, and use phase to select a compatible phase by its lowercase Java name. Rules in the same pack, phase and stage read the same snapshot. Put a consuming rule in a later stage to read an earlier rule's output. Optional before and after lists use logical pack IDs from pack.mcmeta and control generation order for the current pack type. Minecraft's pack priority still decides which file wins between packs. Within one pack, active overlays take precedence over generated files, which take precedence over bundled base files.
Data rules can produce native resources such as recipes, tags, loot tables, functions, and structures, as well as entries in registered world-loaded and reloadable data-pack registries. World-loaded entries such as enchantments regenerate when the world opens. A /reload keeps the full-load output for packs that are still selected. If a pack is disabled and then enabled again in the same world session, its original full-load files become available again. Resource rules execute for local client packs. Server-downloaded ZIPs provide their resolved files directly.
Set "with_metadata": true on a copy rule to copy the source file and its effective .mcmeta sidecar together. The main file's bytes and the sidecar's JSON fields are preserved. The option defaults to false.
{
"op": "copy",
"from": "example:textures/block/fire_template.png",
"to": "example:textures/block/blue_fire.png",
"with_metadata": true
}In a Java callback, use output.copy(destination, source, true) with a file from context.resources(). Use output.copy(destination, source) to copy the main file alone.
The sidecar follows the main file's phase and lifetime. If the source has no sidecar, Cobweb clears an earlier grouped sidecar at the destination and leaves bundled or independently submitted metadata available under native pack priority. on_missing applies to the source file.
Use write with exactly one of json or text to submit a complete file. The json field supplies a JSON value. The text field supplies a string written as UTF-8, including any explicit line breaks. Both forms work for client assets and supported server data.
In assets.rules, this writes a model only when its path is absent from the current stage's visible resource snapshot.
{
"op": "write",
"to": "example:models/block/smooth_stone_variant.json",
"json": {
"parent": "minecraft:block/cube_all",
"textures": {
"all": "minecraft:block/smooth_stone"
}
},
"if_destination": "absent"
}In data.rules, this writes a complete function from an inline string.
{
"op": "write",
"to": "example:function/welcome.mcfunction",
"text": "say Welcome to the world!\n"
}An unconditional write submits its file whether the path exists or is new. Use "if_destination": "present" to require a visible file or "if_destination": "absent" to require a missing path. A failed condition skips the rule by default, equivalent to "on_mismatch": "skip". Set "on_mismatch": "fail" to fail the load instead. Destination checks include visible files from other packs and follow the same stage snapshot as other rule inputs. The output belongs to the rule's own pack and follows native pack priority.
recolor_texture reads a template from from and shades from palette_from. An optional mask limits recoloring to its nontransparent pixels. The output preserves the template's transparency, frame layout and effective metadata. overlay_texture composites a foreground from overlay over the image from from. Both images must be static and the same size. Texture fields use full PNG paths under textures/. Each input PNG can contain up to 1,048,576 decoded pixels and 16 MiB of encoded data. File-rule reads also limit JSON to 8 MiB and copies to 64 MiB; these limits apply while capturing the input. Java callbacks can use the same pixel operations through it.crystalnest.cobweb.api.image.ImageTransforms.
{
"op": "recolor_texture",
"from": "example:textures/block/oak_cabinet.png",
"palette_from": "minecraft:textures/block/spruce_planks.png",
"mask": "example:textures/block/cabinet_wood_mask.png",
"to": "example:textures/block/spruce_cabinet.png"
}A pack's pack.mcmeta can declare a logical ID, a version, and requirements on selected packs of the same type or installed mods. A Cobweb registrar provides the logical ID. The registrar's version and requirement lists replace the corresponding file values, and an explicitly empty list clears the file list. Each pack requirement supplies exactly one of id or native_id.
In Java, use PackReference.logical(Identifier) for a logical ID or PackReference.nativeId(String) for the exact Minecraft repository ID. The factories return PackReference.Logical and PackReference.Native respectively, each with its own id() accessor. The same references work for requirements, queries, and Java exports. An observed PackInfo holds the native ID and the logical ID when available.
For either kind of requirement, omit version to check presence only. Use exact for one version, or supply a lower bound (min or min_exclusive), an upper bound (max or max_exclusive), or both. Version checks use the active loader's rules.
Declare both requirements during mod initialization:
var base = PackReference.logical(Identifier.parse("example:base"));
var local = PackReference.nativeId("file/My Pack.zip");
DataPack.registrar(Identifier.parse("example:addon"))
.requiredPacks(new PackRequirement(base), new PackRequirement(local))
.register();With a running server, use the same references to observe its packs:
var packs = PackQueries.forServer(server);
PackStatus baseApplied = packs.query(base, PackQuestion.APPLIED);
OptionalInt localPosition = packs.position(local, PackOrder.SELECTED);Use PackQueries.client() for live client asset observations and PackQueries.forServer(server) for live data-pack observations. Generation and presentation callbacks receive captured views through context.packs(). REQUESTED refers to the active load's requested stack, and APPLIED refers to the last successful load. The editor view also exposes its proposed selection. Orders run from lowest to highest native priority, with zero-based positions. query() reports UNAVAILABLE when the requested observation has no source in the current view. An empty optional from order() likewise means the observation is unavailable. An observed empty selection returns an empty list inside the optional.
{
"pack": {
"description": "Example add-on",
"min_format": 121,
"max_format": 121
},
"cobweb": {
"id": "example:addon",
"version": "1.0.0",
"requires": {
"packs": [
{"id": "example:base", "version": {"min": "1.0.0", "max_exclusive": "2.0.0"}}
],
"mods": [
{"id": "cobweb"}
]
}
}
}Java requirements use the sealed VersionRange API. Exact stores one version, while Interval stores a lower and an upper bound. Named bound factories specify whether the endpoint itself is accepted:
VersionRange exact = VersionRange.exact("1.2.3");
VersionRange compatible = VersionRange.interval(VersionRange.Bound.inclusive("1.2.0"), VersionRange.Bound.exclusive("2.0.0"));
VersionRange minimum = VersionRange.interval(VersionRange.Bound.inclusive("1.2.0"), null);The compatible interval includes 1.2.0 and excludes 2.0.0. A null endpoint means that side is unbounded; both endpoints cannot be absent. Bound.Inclusion represents INCLUSIVE or EXCLUSIVE when constructing a bound directly. Version comparison uses the active loader's rules for both mod and pack requirements. JSON requirements keep the same exact, min, min_exclusive, max, and max_exclusive fields; an exact version cannot be combined with interval bounds.
Between packs that generate resources, a requirement orders the requiring pack after its dependency during generation.
A mod declares the packs it needs in its own root pack.mcmeta. Add data_packs or asset_packs under cobweb.requires. Cobweb checks the relevant list on each load and reload. Required packs must already be selected. The mod loader supplies the mod's identity and version. Use id and version only inside a requirement to identify and constrain its target pack.
{
"cobweb": {
"requires": {
"data_packs": [{"id": "example:rules"}]
}
}
}Registrars accept presentation(context -> ...) for a partial title, description, or icon override. Use PackQuestion.EDITED_SELECTED to check the editor's proposed selection. PackIcon.modResource can read an icon from ordinary mod assets even while the pack is unselected. Leave fields unset in PackPresentation.builder() to keep their effective base values. Title and description setters accept either components or translation keys. PackPresentations.refresh() refreshes the active client editor without a resource reload.
Use cobweb.title in pack.mcmeta to supply a base title and cobweb.presentation to change how a pack appears in the resource-pack or world-creation data-pack editor. This works for packs with or without generation rules. Each when predicate must match. Later matching entries override the fields they supply. Use self or a logical pack ID with available or edited_selected. A mod_loaded predicate checks for an installed mod. Icon paths are relative to the pack root.
{
"title": {"text": "Stone variants"},
"presentation": [
{
"when": [{"pack": "self", "is": "edited_selected"}],
"title": {"text": "Stone variants (selected)"},
"icon": "icons/selected.png"
},
{
"when": [{"pack": "example:base", "is": "available"}, {"mod_loaded": "example_mod"}],
"description": {"text": "Includes variants for Example Base."}
}
]
}This example shows the contents of the cobweb section. Explicit Java fields override their matching file fields. A Java presentation callback takes over conditional evaluation and can leave fields unset to use the effective base presentation. If an icon cannot be opened, the editor falls back to the base icon. Presentation rules do not change pack activation or ordering.
Java callbacks run on each applicable load by default. Call .cache() on the callback registration to request reuse when Cobweb can verify its inputs. A pack-local string key allows reuse across launches when the callback and environment can be verified. The cache overloads with a fingerprint function cover additional state that affects output. Return a stable string, primitive wrapper or enum; use a canonical string or digest for other types. Unsupported values disable caching with a warning. Registry-independent codecs remain cacheable; reading registry context forces regeneration. If a callback reads metadata, Cobweb checks the effective .mcmeta as well as its absence. Programmatically supplied metadata without a stable file representation causes the callback to run again.
File rules use the cache automatically. Cobweb checks the rule's definition, its observed resources and metadata, and the generation environment before reusing the result. This includes rules that skipped because of a missing source or an unmet destination condition. Cache entries represent the latest successful native load.
Use PackExports.export(PackQueries.client(), PackReference.logical(id)) for applied assets and PackQueries.forServer(server) for applied data. The returned stage completes with the export folder under cobweb/exports. Export applied client assets with /cobweb-export-assets <pack-id>. The local world owner or a dedicated-server administrator can export an applied data pack with /cobweb export <pack-id>.
An export contains the resolved files of that pack, with its active overlays already applied.
A server operator can publish an ordered list of registered Cobweb asset packs in config/cobweb-asset-delivery.json. Packs are listed from lowest to highest priority. If server.properties also configures a resource pack, that pack goes first in the same batch. Minecraft's require-resource-pack and resource-pack-prompt settings apply to the whole batch. Players can receive these packs with an unmodified Minecraft client. Delivered packs must not declare client mod requirements; Cobweb rejects those declarations during publication.
If a download fails or Minecraft discards the batch, Cobweb can retry the ordered batch once within the original timeout. A failed or timed-out optional offer lets the player join. A required offer must apply successfully before the player can join. A player who declines can reconnect and accept the required packs on the next connection.
{
"packs": [
"example:base",
"example:world_assets"
]
}By default the download uses the Minecraft connection's hostname and game port. Set "public_host" to override the hostname. To listen on a different port, add "hosting": "separate-port" and "port": 8080. An optional "bind_address" controls that listener's bind address. Set "public_base_url" to advertise a full HTTP or HTTPS base URL, for example https://packs.example.net/downloads/. A reverse proxy can forward that path to /cobweb/packs/ on the selected listener. To serve the ZIPs directly from another web server, use "hosting": "external", set "public_base_url", and serve the world's cobweb/published-assets directory at that URL.
Bundled assets are published with their active overlays. Add onPublish to generate assets from applied world data. Its first callback runs on the server thread and captures detached data. The second runs on a worker and receives only that value and the publication output. Ordinary client generation callbacks still run locally.
AssetPack.registrar(Identifier.parse("example:world_assets"))
.description(Component.literal("World assets"))
.currentFormat()
.onPublish(server -> server.overworld().getSeed(), (seed, output) -> {
output.putTranslations("example", "en_us", Map.of("example.world.seed", Long.toString(seed)));
})
.register();A successful data reload can publish a new set of ZIPs. Unchanged static packs reuse their archives after content checks. The built-in HTTP host queues up to 64 waiting requests behind eight active downloads, within a 90-second connection deadline. Players receive the latest completed publication when they connect. Players already online receive it on reconnect. An empty pack list disables Cobweb delivery.
If you have any suggestions or questions about this wiki, please open an issue following the Documentation enhancement template.