TESSERA

systems 01

Resource pack

Tessera builds the pack itself on every boot and every /tessera reload, then hashes it and serves it over an embedded HTTP server.

What generation does

  1. Writes pack.png into plugins/Tessera/pack/.
  2. Writes the built-in glyph textures into assets/minecraft/textures/font/ and assets/tessera/textures/font/.
  3. Writes pack.mcmeta with the pack format and a description.
  4. Writes the font provider list, built from the glyph registry, into assets/minecraft/font/default.json and assets/tessera/font/default.json.
  5. Writes the pause menu banner and hud.pause_menu.texts into assets/minecraft/lang/ for every client language. See Glyphs and HUD.
  6. Writes item definitions (assets/<ns>/items/*.json) for items and blocks with a model, and blockstates/note_block.json for custom note blocks. See Items and Blocks.
  7. Checks the pack for broken references. See Pack check.
  8. Zips the whole pack/ folder into plugins/Tessera/tessera-pack.zip.
  9. Applies anti-unzip protection to the archive.
  10. Recomputes the SHA-1 when the file changed and hands it to the pack server.

Your own assets are kept. Lang files you add are merged key by key. Item definitions and blockstates Tessera replaces are remembered in .item-definitions.json and put back when the items that needed them are gone. Put your models, textures and sounds into plugins/Tessera/pack/assets/ and they are zipped with everything else.

Pack check

Every generated pack is scanned for what the client would draw as the purple and black missing texture:

  • a model whose parent or texture does not exist;
  • an item definition or blockstate pointing to a model that does not exist;
  • an item or block in your YAML whose model is not in the pack;
  • a minecraft item definition or blockstate for something that is not in the game;
  • a font bitmap that does not exist;
  • a texture written with .png, upper case letters or other characters the client rejects in a file name;
  • JSON that does not parse.

References into the minecraft namespace under folders vanilla uses, such as block/ and item/, are trusted as vanilla. The first ten problems go to the console on every reload.

/tessera pack doctor

prints the pack analysis and the full list. The importer screen in /tessera admin shows the count.

It then asks whether to fix them. Click [YES], or run /tessera pack doctor fix. A copy of the pack folder is saved to plugins/Tessera/backups/ first, then:

ProblemFix
Upper case or other invalid characters in a file, folder or namespaceRenamed to lower case; every model, item definition and blockstate that points to it is updated.
Texture written with .png.png is cut.
Item definition or blockstate for something that is not in the gameRemoved; the client never used it.
Vanilla item definition, blockstate or model that points to a missing fileRemoved, so the vanilla one is used again.
Broken JSON in the minecraft namespaceRemoved the same way.
Namespace of a mod (it has blockstates) that nothing else usesRemoved; without the mod its blocks and items do not exist.

Your own models and textures that are missing are listed and left alone: only the missing files themselves can fix those. The pack is rebuilt and sent to players afterwards.

Mod namespaces are listed as one line each, for example assets/waystones: assets of a mod (12 broken references), instead of one line per file.

When the pack fails to load for a player, or an admin joins while the pack has problems, admins get a chat message with a clickable /tessera pack doctor button (at most once a minute).

Hosting

pack:
  server:
    enabled: true
    host: "0.0.0.0"
    port: 8085
    domain: "localhost:8085"
    external_url: ""

The server binds to host and port and serves the archive at:

http://<domain>/tessera-pack.zip

domain is what players are sent, so it has to be a host they can reach from outside: a public IP or a domain name, with the port. The port has to be open in your firewall. Set external_url to a CDN or file host if you would rather not serve it yourself. The pack is still built and protected locally.

Downloads are rate limited per IP: rate_limit.max_requests_per_ip downloads within rate_limit.cooldown_minutes, after which the counter resets. Responses carry the SHA-1 in an X-Checksum-SHA1 header. /tessera pack prints the current URL and hash.

Delivery to players

pack:
  server:
    required: true
    kick_on_decline: true
    kick_on_fail: false
    auto_apply:
      enabled: true
      delay_ticks: 10

With auto_apply.enabled, joining players are prompted after delay_ticks. The prompt text, the loading title and subtitle, the success messages and the two kick screens all come from the messages.pack section of config.yml. /tessera pack apply <player|all> re-sends the prompt on demand.

Protecting the player while it loads

pack:
  protect_player:
    enabled: true
    lock_movement: true
    blindness: true
    timeout_seconds: 45

While the client is downloading, the player can be blinded and slowed so they do not walk off a cliff during the freeze. The effects are cleared once the pack is applied or fails.

Anti-unzip

pack:
  protection:
    protect_from_unzip: true
    level: 2

The archive is rewritten so that common desktop unpackers refuse it while the Minecraft client, which reads the central directory, still loads it.

LevelWhat it does
1Clears CRC and size fields in the local file headers.
2Level 1 plus path traversal markers in the local headers.
3Level 2 plus non-standard central directory attribute flags.

Protection makes extraction harder but does not encrypt anything. A determined user can still read the archive.

Importing an existing pack

Drop a .zip into plugins/Tessera/imports/ and run:

/tessera pack import              # every zip in the folder
/tessera pack import mypack.zip   # one file
/tessera pack import https://...  # download first

Or open /tessera admin and the pack importer screen: it lists the zips with their analysis and imports one or all with a click. With pack.importer.auto_watch the folder is polled every watch_interval_seconds and new zips are imported on their own.

Analysis

Before anything is registered, the importer reads the pack the way the client would:

  • pack.mcmeta and its format;
  • legacy overrides with custom_model_data in item models, and 1.21.4+ item definitions that pick models by custom model data;
  • every model reference: item definitions, blockstates, parent and overrides.

From that it decides what kind of pack it is:

KindMeaningWhat is created
RetextureReplaces vanilla models and textures only.Nothing, it works as soon as the pack is sent.
Custom itemsAdds items through custom model data or new models.Items, and furniture for furniture-sized models.
MixedBoth.As above.
Assets onlySounds, fonts or textures.Nothing.

Items are created only for:

  • each custom model data entry, with the material of the item it belongs to (paper.json makes a PAPER item), its number and its model;
  • each item model nothing else refers to and that is not named after a vanilla item, with an item_model.

Blocks are created only for block models outside the minecraft namespace that no blockstate uses. Models nothing can see, such as the door and stair variants of a 3D pack, no longer turn into hundreds of entries. A template left by an older import with the same id and number gets its model added.

Merging

A pack's files are merged into the pack folder, not just copied over it:

FilesMerge
items/*.jsonCustom model data entries of both packs are combined. A plain definition becomes the fallback of the other.
atlases/*.jsonsources are combined.
lang/*.jsonKeys are combined; the new pack wins on the same key.
blockstates/*.jsonVariants and multipart cases are combined.
sounds.json, font/*.jsonCombined, as before.

Anything else that already exists with different content is replaced by the new pack. Every such case, and every custom model data number both packs use, is a conflict. The first ten go to the console, the full list to imports/processed/<pack>.conflicts.txt.

Limits

Downloads are limited to 200 MB. A zip may unpack to at most 1 GB and 100,000 files, and entries that would land outside the pack folder are skipped. Internal network addresses are refused for URL imports.

Import and the pack build run off the main thread, so even a pack with tens of thousands of files does not stall the server. Several imports in a row are followed by one build, and players get the new pack once it is complete.

Every import that created items, blocks or furniture can be taken back:

/tessera pack undo mypack.zip   # tab completion lists the imports

It deletes the YAML files the import created. The textures and models it merged stay in the pack.

Packs made for mods are recognised: a namespace with blockstates or lang files, or any namespaced item model in a pack older than 1.21.4, belongs to a mod, and no Tessera items are made from it.

Pack format

pack.mcmeta is written with the format from pack.meta.pack_format, default 84 (26.1). It declares support for formats 34 to 99, both the old way (supported_formats) and the new one (min_format and max_format), so 1.21 and 26.x clients accept it.