Skip to content

Creating Profile v3

Jump to bottom
0Templ edited this page Jul 7, 2026 · 5 revisions

Profile File Location

Soft Imprints loads profiles from resource assets.

Path format: assets/<namespace>/imprint_profiles/<profile_id>.json

Example: assets/my_pack/imprint_profiles/mud.json

Basic Structure

Each profile is a single JSON object.

A v3 profile can contain these top-level sections:

Field Required
version Recommended
supported_blocks Recommended
surface No
layers Yes
texture_sets Yes
resolution No
decay No
priority No
preview No

Some optional sections use default behavior when omitted.

The following sections describe each group of fields in detail.

Version

version declares the profile schema version.

Example:

"version": 3

Use version: 3 for new profiles.

Older profile schemas are migrated in memory when possible.

Profiles with a newer schema version than the installed mod supports are rejected.

For compatibility rules, see Schema Versions.

Supported Blocks

supported_blocks assigns the profile to blocks.

When a block matches this list, Soft Imprints can use this profile for imprints on that block.

Format: array of block ids

Example:

["minecraft:mud"]

A profile without supported_blocks can still load, but it will not be assigned to any block by default.

This is useful only for advanced setups where another resolver or integration selects the profile manually.

If multiple profiles support the same block, Soft Imprints uses profile priority to choose which one wins.

See Priority.

Surface

surface controls how the base surface under the imprint is rendered.

Example:

"surface": {
  "mode": "repaint",
  "zero_layer_source": "surface"
}
Field Default Values
mode repaint repaint, overlay
zero_layer_source surface surface, profile

repaint replaces the original top face and redraws the surface with imprint layers.

overlay keeps the original block model and draws imprints slightly above the surface.

zero_layer_source is used by repaint mode:

  • surface uses the block's current top texture as the base.
  • profile uses texture_sets.zero_layer from this profile.

Layers

layers describes imprint depth layers.

Each layer has a numeric value. This value is written into the imprint map and matched with textures from texture_sets.

Lower values are deeper. 0 means no imprint.

Example:

"layers": [
  {
    "value": 1,
    "enable": true,
    "expand": 0,
    "inner_jitter": 0.0,
    "outer_jitter": 0.05,
    "erosion": 0.25
  },
  {
    "value": 2,
    "enable": true,
    "expand": 2,
    "inner_jitter": 0.0,
    "outer_jitter": 0.4,
    "erosion": 0.1
  }
]
Field Required Values Description
value Yes 1-127 Layer id. Must match texture keys in texture_sets.textures_by_value.
enable Yes true, false Whether this layer is used.
expand No integer Expands this layer outward.
inner_jitter No 0.0-1.0 Adds noise along the inner edge of this layer.
outer_jitter No 0.0-1.0 Adds noise along the outer edge of this layer.
erosion No 0.0-1.0 Randomly removes cells from this layer.

Every enabled layer must have a matching texture entry in each texture set.

Layer values determine depth order. Mod sorts layers by value. Lower values are deeper.

Texture Sets

texture_sets defines the textures used by the profile.

A profile can provide multiple texture sets. The player can switch between them in the config screen.

Example:

"texture_sets": {
  "selected": "standard",
  "zero_layer": "minecraft:block/snow",
  "textures_by_value": {
    "standard": {
      "1": "my_pack:block/imprints/mud/sets/standard_mud_layer_1",
      "2": "my_pack:block/imprints/mud/sets/standard_mud_layer_2"
    },
    "wet": {
      "1": "my_pack:block/imprints/mud/sets/wet_mud_layer_1",
      "2": "my_pack:block/imprints/mud/sets/wet_mud_layer_2"
    }
  }
}
Field Required Description
selected Yes Default texture set id. Must exist in textures_by_value.
zero_layer Yes Base/fallback texture. Used by surface.zero_layer_source: profile and as preview fallback.
textures_by_value Yes Texture sets mapped by set id.

Inside textures_by_value, each texture set maps layer values to block texture ids.

Layer values must match layers[].value.

Texture ids should not include .png.

For example, this texture id:

my_pack:block/imprints/mud/sets/standard_mud_layer_1

points to this file:

assets/my_pack/textures/block/imprints/mud/sets/standard_mud_layer_1.png

Decay

decay controls whether imprints from this profile disappear over time.

A profile without a decay section does not decay.

Decay also requires the global decay switch in the mod settings to be enabled(config part - not related to profiles).

Example:

"decay": {
  "enabled": true,
  "grace_seconds": 30,
  "ramp_seconds": 30,
  "chance": 0.04,
  "depth_bias": 0.5
}
Field Required Default Description
enabled Yes false Enables decay for this profile.
grace_seconds No 30 Time before imprints start decaying.
ramp_seconds No 30 Time over which decay reaches full speed after the grace period.
chance No 0.04 Base chance for an edge cell to step one layer shallower.
depth_bias No 0.5 How much deeper layers resist decay.

Priority

priority decides which profile wins when multiple profiles support the same block.

Higher priority wins.

Default: 100

Example: "priority": 150

If two profiles have the same priority, Soft Imprints uses a stable fallback order based on the profile source key.

Use priority when you want a profile to override another profile for the same block.

For example, a resource pack profile with priority 150 will win over a default profile with priority 100.

Preview

preview defines optional assets used by the config UI.

If preview is omitted, Soft Imprints uses texture_sets.zero_layer as the preview base and icon.

Example:

"preview": {
  "base": "my_pack:block/imprints/mud/mud_base",
  "icon": "my_pack:icon/mud/mud_icon",
  "landing_sound": "minecraft:block.mud.place"
}
Field Required Default Description
base No texture_sets.zero_layer Base texture used in the profile preview. It is block texture id.
icon No texture_sets.zero_layer Icon used in profile selectors. It is a GUI sprite id.
landing_sound No none Sound event played by profile UI interactions.

Texture ids should not include .png.

Sound ids should point to existing Minecraft or resource-pack sound events.

Translations

Profiles and texture sets can have translated display names.

Add translations to your resource pack language file:

assets/<namespace>/lang/en_us.json

Example:

{
  "imprint_profile.my_pack.mud": "Mud",
  "imprint_profile.my_pack.mud.standard": "Standard",
  "imprint_profile.my_pack.mud.wet": "Wet",
  "imprint_pack.my_pack": "My Imprint Pack"
}
Key Description
imprint_profile.<namespace>.<profile_id> Profile display name.
imprint_profile.<namespace>.<profile_id>.<texture_set_id> Texture set display name.
imprint_pack.<namespace> Profile pack/group display name.

For the profile id my_pack:mud, the profile translation key is:

imprint_profile.my_pack.mud

For the texture set wet, the texture set translation key is:

imprint_profile.my_pack.mud.wet

If a translation is missing, Minecraft will show the raw translation key.

Example Profile

This example adds imprints for minecraft:mud.

{
  "version": 3,
  "supported_blocks": [
    "minecraft:mud"
  ],
  "surface": {
    "mode": "repaint",
    "zero_layer_source": "surface"
  },
  "texture_sets": {
    "selected": "standard",
    "zero_layer": "minecraft:block/mud",
    "textures_by_value": {
      "standard": {
        "1": "my_pack:block/imprints/mud/sets/standard_mud_layer_1",
        "2": "my_pack:block/imprints/mud/sets/standard_mud_layer_2"
      },
      "wet": {
        "1": "my_pack:block/imprints/mud/sets/wet_mud_layer_1",
        "2": "my_pack:block/imprints/mud/sets/wet_mud_layer_2"
      }
    }
  },
  "preview": {
    "base": "my_pack:block/imprints/mud/mud_base",
    "icon": "my_pack:icon/mud/mud_icon"
    "landing_sound": "minecraft:block.mud.place"
  },
  "decay": {
    "enabled": true,
    "grace_seconds": 30,
    "ramp_seconds": 30,
    "chance": 0.04,
    "depth_bias": 0.5
  },
"layers": [
    {
      "value": 1,
      "enable": true,
      "expand": 0,
      "inner_jitter": 0.0,
      "outer_jitter": 0.05,
      "erosion": 0.25
    },
    {
      "value": 2,
      "enable": true,
      "expand": 2,
      "inner_jitter": 0.0,
      "outer_jitter": 0.4,
      "erosion": 0.1
    }
  ]
}

This profile expects texture files such as:

assets/my_pack/textures/block/imprints/mud/standard_layer_1.png

assets/my_pack/textures/block/imprints/mud/wet_layer_1.png

assets/my_pack/textures/block/imprints/mud/preview_base.png

assets/my_pack/textures/icon/mud.png

Recommended Asset Structure

Recommended structure for a my_pack:mud profile:

assets/
└── my_pack/
    ├── imprint_profiles/
    │   └── mud.json
    ├── lang/
    │   └── en_us.json
    └── textures/
        ├── block/
        │   └── imprints/
        │       └── mud/
        │           ├── mud_base.png
        │           └── sets/
        │               ├── standard_mud_layer_1.png
        │               ├── standard_mud_layer_2.png
        │               ├── wet_mud_layer_1.png
        │               └── wet_mud_layer_2.png
        └── gui/
            └── sprites/
                └── icon/
                    └── mud/
                        └── mud_icon.png

Clone this wiki locally