Asset System Overview

Asset System Overview

The Asset System manages all game content including blocks, items, entities, sounds, particles, and more. Assets are defined in JSON files and can be bundled with plugins.

Package Location

com.hypixel.hytale.server.core.asset.type

Asset Pack Structure

Asset packs follow a specific directory structure:

• Directorymy-plugin.jar/

  • manifest.json
  • Directoryassets/

    • Directoryblocktype/ Block definitions

      • …
    • Directoryitem/ Item definitions

      • …
    • Directorymodel/ 3D models

      • …
    • Directorysoundevent/ Sound events

      • …
    • Directorysoundset/ Sound collections

      • …
    • Directoryparticle/ Particle systems

      • …
    • Directoryweather/ Weather configurations

      • …
    • Directoryentity/ Entity definitions

      • …
    • Directoryentityeffect/ Status effects

      • …
    • Directoryenvironment/ Environment settings

      • …
    • Directoryambiencefx/ Ambient effects

      • …
    • Directorygameplay/ Gameplay configurations

      • …

Core Asset Types

Block Types (blocktype/)

Define block behavior and properties:

{
  "Id": "MyPlugin_CustomBlock",
  "Group": "MyBlocks",
  "DrawType": "Cube",
  "Material": "Solid",
  "Opacity": "Solid",
  "Textures": [
    {
      "Up": "textures/block_top.png",
      "Down": "textures/block_bottom.png",
      "North": "textures/block_side.png",
      "South": "textures/block_side.png",
      "East": "textures/block_side.png",
      "West": "textures/block_side.png"
    }
  ],
  "HitboxType": "Full",
  "BlockSoundSetId": "Hytale/Stone",
  "Light": {
    "Color": "#FFAA00",
    "Intensity": 10
  }
}

Key properties:

Property	Type	Description
Id	string	Unique block identifier
Group	string	Grouping for organization
DrawType	enum	Rendering type (Empty, Cube, Model, CubeWithModel, GizmoCube)
Material	enum	Physical material (Empty or Solid)
Opacity	enum	Light blocking (Solid, Transparent, SemiTransparent)
Textures	array	Per-face texture definitions
HitboxType	string	Collision hitbox type
BlockSoundSetId	string	Sound set reference
Light	object	Emitted light with Color and Intensity

Items (item/)

Define items and their behavior:

{
  "Id": "MyPlugin_CustomSword",
  "DisplayName": "Custom Sword",
  "Model": "MyPlugin/sword_model",
  "MaxStack": 1,
  "MaxDurability": 500,
  "AttackDamage": 7.0,
  "AttackSpeed": 1.6,
  "Tags": ["weapon", "sword"]
}

Key properties:

Property	Type	Description
Id	string	Unique item identifier
DisplayName	string	Localized display name
MaxStack	int	Maximum stack size
MaxDurability	float	Maximum durability (0 = unbreakable)
AttackDamage	float	Melee damage
Tags	string[]	Item categorization tags

Sound Events (soundevent/)

Sound events use a layered system where each layer contains a list of audio files (one chosen at random), with per-layer volume, looping, and randomization settings.

{
  "Layers": [
    {
      "Files": [
        "Sounds/Items/Chest/Chest_Open.ogg"
      ]
    }
  ],
  "Volume": 2.0,
  "Parent": "SFX_Attn_Quiet"
}

Top-level properties:

Property	Type	Description
Volume	float	Volume adjustment in decibels (-100 to 10)
Pitch	float	Pitch adjustment in semitones (-12 to 12)
Layers	SoundEventLayer[]	Layered sounds that make up this event
AudioCategory	string	Audio category for volume routing
MaxInstance	int	Max concurrent instances (1-100, default 50)
PreventSoundInterruption	bool	Prevent overlap interruption
StartAttenuationDistance	float	Distance (blocks) to begin attenuation
MaxDistance	float	Max audible distance in blocks

Layer properties:

Property	Type	Description
Files	string[]	Audio file paths (one chosen at random)
Volume	float	Layer volume offset in dB
Looping	bool	Whether this layer loops
Probability	int	Chance of playing (percentage)
RandomSettings	object	Randomization (MinVolume, MaxVolume, MinPitch, MaxPitch, MaxStartOffset)

Particles (particle/)

Particle systems combine multiple spawner references into a single effect. The particle/ directory contains .particlesystem files, while individual emitter configurations live in .particlespawner files.

{
  "Id": "MyPlugin_CustomParticle",
  "Spawners": [
    {
      "SpawnerId": "MyPlugin:MySpawner"
    }
  ],
  "LifeSpan": 2.0,
  "CullDistance": 64.0,
  "BoundingRadius": 5.0,
  "IsImportant": false
}

Key properties:

Property	Type	Description
Id	string	Unique particle system identifier
Spawners	ParticleSpawnerGroup[]	Array of spawner group references
LifeSpan	float	Duration of the particle system in seconds
CullDistance	float	Distance at which the system stops rendering
BoundingRadius	float	Bounding sphere radius for culling
IsImportant	bool	Whether this system should always render regardless of particle settings

See Particles for the full spawner and system reference.

Entity Effects (entityeffect/)

Entity effects are status effects that modify stats, deal damage over time, change visuals, and more. They use a stat modifier system rather than simple key-value effects.

{
  "Id": "MyPlugin_CustomEffect",
  "Name": "effect.custom",
  "Duration": 10.0,
  "Debuff": true,
  "StatModifiers": {
    "MovementSpeed": -0.3
  },
  "ApplicationEffects": {
    "EntityBottomTint": "#00FF00",
    "HorizontalSpeedMultiplier": 0.7,
    "WorldSoundEventId": "SFX_Effect_Poison"
  },
  "StatusEffectIcon": "ui/icons/custom_effect"
}

Key properties:

Property	Type	Description
Name	string	Localization key for display name
Duration	float	Default duration in seconds
Infinite	bool	Whether the effect lasts forever
Debuff	bool	Whether this is a negative effect
StatModifiers	map<string, float>	Stat modifications to apply
ValueType	enum	Absolute or Percent for stat modifiers
ApplicationEffects	object	Visual/audio effects on application (tints, particles, sounds)
DamageCalculator	object	Damage-over-time configuration
StatusEffectIcon	string	Icon shown in the UI
OverlapBehavior	enum	IGNORE, EXTEND, or OVERWRITE
Invulnerable	bool	Makes entity invulnerable while active

Weather (weather/)

Weather assets control visual sky, fog, and lighting properties using time-based keyframes. Each property is an array of { Hour, Color/Value } entries that interpolate across the 24-hour day cycle.

{
  "Id": "MyPlugin_ClearWeather",
  "Stars": "textures/sky/stars_default",
  "FogDistance": [-96.0, 1024.0],
  "SunlightColors": [
    { "Hour": 6.0, "Color": "#FFCC88" },
    { "Hour": 12.0, "Color": "#FFFFFF" }
  ],
  "SkyTopColors": [
    { "Hour": 0.0, "Color": "#112244FF" },
    { "Hour": 12.0, "Color": "#4488CCFF" }
  ],
  "FogColors": [
    { "Hour": 0.0, "Color": "#1A1A2E" },
    { "Hour": 12.0, "Color": "#C0C8D0" }
  ],
  "Clouds": [
    {
      "Texture": "textures/sky/clouds_default",
      "Colors": [
        { "Hour": 0.0, "Color": "#333344AA" },
        { "Hour": 12.0, "Color": "#FFFFFFCC" }
      ],
      "Speeds": [
        { "Hour": 0.0, "Value": 0.5 }
      ]
    }
  ],
  "Particle": {
    "SystemId": "Hytale:RainParticle",
    "Color": "#AABBCC",
    "Scale": 1.0,
    "OvergroundOnly": true
  }
}

Weather uses three keyframe types:

• TimeColor: { "Hour": 0.0-24.0, "Color": "#RRGGBB" }
• TimeColorAlpha: { "Hour": 0.0-24.0, "Color": "#RRGGBBAA" }
• TimeFloat: { "Hour": 0.0-24.0, "Value": float }

See Weather for the full property reference.

Gameplay (gameplay/)

GameplayConfig is a composite asset containing sub-configurations for many gameplay systems:

{
  "Id": "MyPlugin_GameplayConfig",
  "Gathering": { },
  "World": { },
  "Death": { },
  "Respawn": { },
  "Combat": { },
  "Player": { },
  "ItemDurability": { },
  "ItemEntity": { },
  "Crafting": { },
  "Spawn": { },
  "Plugin": { },
  "CameraEffects": { },
  "ShowItemPickupNotifications": true,
  "MaxEnvironmentalNPCSpawns": 500
}

Sub-configurations:

Key	Config Class	Description
Gathering	GatheringConfig	Block gathering/mining settings
World	WorldConfig	World behavior settings
Death	DeathConfig	Death behavior and drops
Respawn	RespawnConfig	Respawn mechanics
Combat	CombatConfig	Combat mechanics
Player	PlayerConfig	Player settings
ItemDurability	ItemDurabilityConfig	Durability rules
ItemEntity	ItemEntityConfig	Dropped item entity settings
Crafting	CraftingConfig	Crafting system settings
Spawn	SpawnConfig	Spawn mechanics
Plugin	map	Plugin-specific config (extensible)
CameraEffects	CameraEffectsConfig	Camera effect settings

Accessing Assets in Code

Get Asset by ID

// Block types
BlockType blockType = BlockType.getAssetMap().get("MyPlugin_CustomBlock");

// Items
Item item = Item.getAssetMap().get("MyPlugin_CustomSword");

// Weather
Weather weather = Weather.getAssetMap().get("MyPlugin_CustomWeather");

// Entity effects
EntityEffect effect = EntityEffect.getAssetMap().get("MyPlugin_CustomEffect");

Asset Maps

Each asset type has an AssetMap for lookups:

AssetMap<BlockType> blockTypes = BlockType.getAssetMap();

// Get by key
BlockType block = blockTypes.get("Block_Key");

// Get all keys
Set<String> keys = blockTypes.keySet();

// Check existence
boolean exists = blockTypes.containsKey("Some_Block");

// Get index (for network serialization)
int index = blockTypes.getIndex("Block_Key");

Registering Assets

In Plugin Manifest

Set IncludesAssetPack in manifest.json:

{
  "Name": "MyPlugin",
  "IncludesAssetPack": true
}

Programmatic Registration

@Override
protected void setup() {
    // Register custom asset type handler
    getAssetRegistry().register(/* asset registration */);
}

Asset Modifiers

Modify existing assets at runtime:

// Get block type
BlockType stone = BlockType.getAssetMap().get("Block_Stone");

// Assets are typically immutable
// Use asset overrides in your asset pack instead

New in Update 3

A new FileIO abstraction layer was added in com.hypixel.hytale.procedurallib.file. It introduces a virtual file system with multi-root support, enabling asset overlaying where mod assets can override base assets. JsonLoader now loads files through FileIO instead of direct Files.newBufferedReader calls, and includes path traversal protection to prevent directory traversal attacks. The Update 3 changelog covers all asset system changes.

Asset Pack Priority

When multiple packs define the same asset, priority determines which is used:

1. Core Assets: Base game assets (lowest priority)
2. Plugin Assets: In order of plugin loading
3. Override Packs: Explicit overrides (highest priority)

Asset Validation

Assets are validated on load:

// Assets use validators
BuilderCodec<Item> codec = Item.CODEC;

// Validation includes:
// - Required fields
// - Value ranges
// - Reference validity
// - Type constraints

Asset Serialization

Assets use the Codec system for serialization:

// Most assets have a CODEC
BuilderCodec<BlockType> blockCodec = BlockType.CODEC;
BuilderCodec<Item> itemCodec = Item.CODEC;

// Serialize to BSON
BsonDocument doc = codec.encode(asset, extraInfo);

// Deserialize
Asset loaded = codec.decode(doc, extraInfo);

Asset Hot-Reloading

The server supports hot-reloading of assets during development:

• Assets in development packs can be reloaded
• Connected clients receive updated asset data
• Not all asset changes take effect immediately

Complete Asset Type List

All 35 asset types organized by category:

Content Assets

Directory	Class	Description
blocktype/	BlockType	Block definitions
blockset/	BlockSet	Block groupings
item/	Item	Item definitions
fluid/	Fluid	Fluid types
projectile/	Projectile	Projectile definitions

Visual Assets

Directory	Class	Description
model/	Model	3D models
particle/	Particle	Particle systems
trail/	Trail	Trail effects
modelvfx/	ModelVFX	Model visual effects
fluidfx/	FluidFX	Fluid visual effects
blockbreakingdecal/	BlockBreakingDecal	Break animation overlays
blockhitbox/	BlockBoundingBoxes	Block collision shapes
blockparticle/	BlockParticleSet	Block particle effects

Audio Assets

Directory	Class	Description
soundevent/	SoundEvent	Individual sounds
soundset/	SoundSet	Sound collections
blocksound/	BlockSoundSet	Block-specific sounds
itemsound/	ItemSoundSet	Item-specific sounds
audiocategory/	AudioCategory	Audio categories
equalizereffect/	EqualizerEffect	Audio equalizer effects
reverbeffect/	ReverbEffect	Audio reverb effects

World Assets

Directory	Class	Description
weather/	Weather	Weather systems
environment/	Environment	Environment settings
ambiencefx/	AmbienceFX	Ambient effects
portalworld/	PortalWorld	Portal world definitions

Gameplay Assets

Directory	Class	Description
gameplay/	GameplayConfig	Gameplay configuration
gamemode/	GameMode	Game mode definitions
entityeffect/	EntityEffect	Status effects
attitude/	Attitude	NPC attitudes
camera/	Camera	Camera configurations
itemanimation/	ItemAnimation	Item animations
blocktick/	TickProcedure	Block tick procedures

Utility Assets

Directory	Class	Description
buildertool/	BuilderTool	Builder tools
tagpattern/	TagPattern	Tag matching patterns
responsecurve/	ResponseCurve	Mathematical curves
wordlist/	WordList	Word lists for generation

Best Practices

1. Use unique prefixes: Prefix asset IDs with your plugin name
2. Validate references: Ensure referenced assets exist
3. Provide defaults: Include sensible default values
4. Document assets: Comment complex configurations
5. Test combinations: Verify assets work together
6. Consider performance: Avoid overly complex particle systems

Related

• Block Types - Detailed block documentation
• Items - Item system overview
• Sound Events - Audio system
• Particles - Particle system