Installation

1. Install PlaceholderAPI
2. Install tozanstwAssets
3. Start the server once
4. Stop the server
5. Place your textures under
   Code (Text):

   plugins/tozanstwAssets/textures/
6. Create or edit
   Code (Text):

   assets.yml
7. Edit
   Code (Text):

   config.yml
8. Set your public pack-server IP or domain
9. Start the server again
10. Run
    Code (Text):

    /tstw zip
11. Reconnect and test the pack

Folder Structure

Recommended layout:
Recommended category use:
- emojis for general inline icons
- twitteremojis for large emoji libraries
- logos for branding assets
- ranks for badges and role visuals
- guis for large overlays, menu headers and special screen textures

How assets are defined

Assets are loaded from .

Each top-level entry becomes a registered glyph with its own:
- id
- symbol
- scale ratio
- vertical position
- texture path
- optional permission
- GUI visibility setting
- optional menu behavior

Example:
Field Reference

• permission
  Permission node required for inline replacement.
  
• show_in_gui
  If true, the asset appears in the Assets Dictionary book.
  
• path
  Path relative to:
  
  Code (Text):

  plugins/tozanstwAssets/textures/
• scale_ratio
  Controls the bitmap font height written into the generated font provider.
  
• y_position
  Controls ascent / vertical alignment.
  
• is_menu
  Marks the asset as a menu-style glyph.

Path Handling Details

Standard asset entries in are commonly written without the extension.

Example:
The plugin appends automatically if it is missing.

Custom screen entries in are commonly written with the extension already included.

Example:
Permissions

Admin permission
Text effect permissions
Per-asset permissions

Each asset can define its own permission in .

If a player uses inline placeholders such as , replacement only happens if:
- the player is OP, or
- the player has the required asset permission

How to use assets in text

Inline format:
Examples:
Where inline formatting is applied

The plugin processes text in:
- player chat
- sign text
- anvil result names
- editable book pages
- editable book titles

Text Effect Tags

Supported tags:
Exact internal color mappings:
Examples:
The tags are case-insensitive.

Hex and Color Code Support

The plugin supports:
- hex syntax in the form - standard color codes

Example:
PlaceholderAPI Support

Placeholder identifier:
Basic format:
Examples:
If the requested asset is animated, PlaceholderAPI automatically returns the correct frame.

Important note about permissions

Inline replacement checks the player’s asset permission.
PlaceholderAPI output itself returns the glyph directly.

Offset Placeholders

Format:
Examples:
These are useful for:
- precise alignment
- HUD layouts
- menu composition
- spacing tricks
- language overwrite positioning

Animated Asset Support

Animated assets are supported automatically.

An asset is treated as animated when:
- the PNG height is greater than its width
- the total height is evenly divisible by the width

Examples:
- 16x64 = 4 frames of 16x16
- 32x128 = 4 frames of 32x32
- 64x320 = 5 frames of 64x64

If an animation is detected:
- the plugin slices the frames during pack generation
- extra internal frame glyphs are assigned automatically
- PlaceholderAPI returns the active frame over time

Optional .mcmeta support

If a matching file exists next to the PNG, the plugin reads its animation frametime.

If no frametime is provided, the default frame time is 2 ticks.

Assets Dictionary Book

Command:
This opens a written book called Assets Dictionary.

The book:
- lists assets where - shows the glyph
- shows the correct usage format
- adds a hover tooltip
- lets players click an entry to suggest the correct text in chat

The current layout stores up to 10 listed assets per page.

Built-in Resource Pack Generation

Use:
The plugin will:

1. clear the previous generated pack folder
2. create a fresh
   Code (Text):

   generated_pack
   directory
3. write
   Code (Text):

   pack.mcmeta
4. copy
   Code (Text):

   pack.png
   if present
5. copy source textures into the output namespace
6. split animated textures into frame files
7. build
   Code (Text):

   assets/minecraft/font/default.json
8. add spacing providers for offset characters
9. write language override files
10. add optional custom screen assets
11. add optional UI-tweak files
12. copy optional shader files from the plugin folder
13. compress everything into
    Code (Text):

    pack.zip
14. calculate a SHA-1 hash
15. store the hash in config
16. build a pack URL
17. send the pack to online players

Pack Generation Feedback

During , the player running the command receives a progress bossbar with stages such as:
- Initializing System
- Reading Textures
- Generating JSON Data
- Encrypting Assets
- Compressing Pack

After generation, the command reports:
- generated path
- final URL
- pack size
- approximate percentage of the 250 MB client limit
- number of online players who received the pack

Pack Namespace

Default namespace:
Generated textures are written under:
To change it:
Pack Icon and Metadata

Config example:
This controls:
- pack format
- visible pack description
- pack icon file copied into the generated pack

Texture Obfuscation

Config:
When enabled, generated texture files are written with randomized names under an path inside the pack instead of keeping original readable file names.

ZIP Protection Options

Config:
When enabled, the plugin injects additional fake or invalid file entries into the ZIP archive.

This is not a replacement for real security.
Use it carefully and test your final ZIP before public deployment.

Built-in Pack Server

Default config example:
The generated pack is served from:
Join-time pack URLs are sent in the format:
Important Deployment Note

The default example config uses:
That only works for local testing.

For real players, change it to:
- your public IP
- or your domain / reverse proxy target

and make sure the selected port is reachable from outside your machine.

Pack Hash Handling

After generating , the plugin calculates its SHA-1 hash and stores it in config.

Stored value:
If a valid stored hash exists, the plugin sends the resource pack with the hash included.

Join-time Pack Sending and Enforcement

Relevant config:
Behavior:
- on join, the pack is sent automatically
- if a player declines the pack and is enabled, the player is kicked
- if the pack download fails and is enabled, the player is kicked
- if the pack loads successfully, the configured success message is sent

Pack Server Protection

Config:
This includes:
- browser-style request blocking
- request rate limiting
- temporary cooldown after repeated failures

Custom Screen Assets

Config example:
Built-in screen IDs:
minecraft_lang_overwrite

The plugin can generate language files under:
Config example:
Supported inline replacements include:
If contains , the generator writes:
- en_us
- tr_tr
- en_gb
- de_de
- es_es
- fr_fr
- ru_ru

UI Tweak Options

Config example:
hide-bossbar
Generates transparent bossbar textures.

hide-buttons
Generates transparent widget button textures.

hide-scoreboard-background
Writes a shader override for that discards the dark translucent text background.

Shaders Folder Support

If a folder exists inside the plugin folder, the generator copies it into:
Action Bar HUD System

Config example:
A STATUS HUD:
- reads a numeric player stat
- converts that value into full icons
- adds one half icon if needed
- fills remaining slots with the negative / empty icon

Typical uses:
- mana bars
- stamina bars
- energy bars
- custom RPG resource displays

Developer note

The HUD renderer is included, but the actual stat values must still be set by your own server logic or integration.

Stat Manager

The internal stat manager stores float values per player and per stat name.

Typical stat names:
- mana
- stamina
- rage
- soul
- energy
- ammo
- heat

Admin Inventory

Running:
opens the main inventory GUI.

The menu listener is wired so that specific slot groups trigger:
- reload
- zip generation
- asset dictionary opening

Recommended Workflow for Large Asset Packs

1. sort images into folders first
2. keep asset IDs short and predictable
3. use category-based permission naming
4. keep GUI assets separate from public chat assets
5. keep large overlays in the
   Code (Text):

   guis
   folder
6. regenerate the pack after each major texture change
7. test animated assets separately
8. test pack download from an external network, not just localhost
9. test language override screens after every layout change

Practical Notes

- PlaceholderAPI placeholders return glyph output directly, while inline replacement checks player permissions.
- Animation detection depends on texture dimensions, so make sure sprite strips are formatted correctly.
- The built-in pack server is practical for self-hosted workflows, but you still need proper public networking if real players will download from it.
- ZIP protection toggles are optional and should be tested carefully before public use.
- The pack generator is the heart of the workflow. After texture, config or language changes, regenerate the pack.