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
- Writes
pack.pngintoplugins/Tessera/pack/. - Writes the built-in glyph textures into
assets/minecraft/textures/font/andassets/tessera/textures/font/. - Writes
pack.mcmetawith the pack format and a description. - Writes the font provider list, built from the glyph registry, into
assets/minecraft/font/default.jsonandassets/tessera/font/default.json. - Writes the pause menu banner and
hud.pause_menu.textsintoassets/minecraft/lang/for every client language. See Glyphs and HUD. - Writes item definitions (
assets/<ns>/items/*.json) for items and blocks with amodel, andblockstates/note_block.jsonfor custom note blocks. See Items and Blocks. - Checks the pack for broken references. See Pack check.
- Zips the whole
pack/folder intoplugins/Tessera/tessera-pack.zip. - Applies anti-unzip protection to the archive.
- 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
parentor 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
modelis 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:
| Problem | Fix |
|---|---|
| Upper case or other invalid characters in a file, folder or namespace | Renamed 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 game | Removed; the client never used it. |
| Vanilla item definition, blockstate or model that points to a missing file | Removed, so the vanilla one is used again. |
| Broken JSON in the minecraft namespace | Removed the same way. |
| Namespace of a mod (it has blockstates) that nothing else uses | Removed; 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.
| Level | What it does |
|---|---|
| 1 | Clears CRC and size fields in the local file headers. |
| 2 | Level 1 plus path traversal markers in the local headers. |
| 3 | Level 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.mcmetaand its format;- legacy
overrideswithcustom_model_datain item models, and 1.21.4+ item definitions that pick models by custom model data; - every model reference: item definitions, blockstates,
parentand overrides.
From that it decides what kind of pack it is:
| Kind | Meaning | What is created |
|---|---|---|
| Retexture | Replaces vanilla models and textures only. | Nothing, it works as soon as the pack is sent. |
| Custom items | Adds items through custom model data or new models. | Items, and furniture for furniture-sized models. |
| Mixed | Both. | As above. |
| Assets only | Sounds, fonts or textures. | Nothing. |
Items are created only for:
- each custom model data entry, with the material of the item it belongs to (
paper.jsonmakes aPAPERitem), its number and itsmodel; - 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:
| Files | Merge |
|---|---|
items/*.json | Custom model data entries of both packs are combined. A plain definition becomes the fallback of the other. |
atlases/*.json | sources are combined. |
lang/*.json | Keys are combined; the new pack wins on the same key. |
blockstates/*.json | Variants and multipart cases are combined. |
sounds.json, font/*.json | Combined, 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.