Facehugger Head Offset Datapack Entries

This page explains how to add or override facehugger positioning data through a datapack. These entries control where a facehugger is translated while riding a supported host entity.

What these entries do

Facehugger rendering uses two pieces of data:

1. Head data from the built-in entity head table.
   • This defines the host entity's head size, position, and pivot.
   • These values are stored in code, not in this datapack system.
2. Head offset data from datapack JSON files.
   • This defines the final vertical and forward/back face placement expressions.
   • These are the values you can add or override with datapacks.

When a facehugger is riding an entity, the renderer checks whether the host has built-in EntityHeadData. If the host has no built-in head data, the facehugger positioning code returns early and no datapack offset entry will be used.

Datapack folder structure

Create a datapack with this structure:

my_facehug_offsets/
├─ pack.mcmeta
└─ data/
   └─ <namespace>/
      └─ ovomorphosis_head_offsets/
         └─ <entry_name>.json

Example:

my_facehug_offsets/
├─ pack.mcmeta
└─ data/
   └─ mypack/
      └─ ovomorphosis_head_offsets/
         ├─ cow.json
         ├─ villager.json
         └─ hoglin.json

Basic JSON format

Each JSON file defines offsets for one entity type.

{
  "entity": "minecraft:cow",
  "vertical_offset": "-size_y",
  "face_offset": "size_z + (size_z / 2) + parasite_height"
}

Fields

Field	Required	Description
entity	No, but recommended	The entity type ID this entry applies to, such as minecraft:cow.
vertical_offset	Yes	Expression used for the Y translation. Negative values usually move the facehugger upward/downward relative to the transformed head space, depending on the current render transform.
face_offset	Yes	Expression used for the Z translation, usually controlling how far forward the facehugger sits on the host's face.

If entity is omitted, the loader falls back to minecraft:<file_path>. For example, cow.json without an entity field resolves to minecraft:cow. This is convenient for vanilla entities, but you should include entity for clarity and for modded entities.

Available expression variables

Offset expressions are evaluated using the host head data and the parasite entity's bounding box.

Variable	Meaning
size_x	Host head width.
size_y	Host head height.
size_z	Host head depth.
pivot_x	Host head pivot X.
pivot_y	Host head pivot Y.
pivot_z	Host head pivot Z.
parasite_height	Facehugger bounding-box height.
parasite_width	Facehugger bounding-box width.

Expressions are strings, not raw JSON numbers. Use arithmetic expressions such as:

"-size_y"

"size_z + (size_z / 2) + parasite_height"

"size_z - 0.2"

The exact supported grammar is defined by OffsetExpression in code. In normal entries, stick to simple arithmetic with variables, numbers, parentheses, and operators such as +, -, *, and /.

Example entries

Cow

{
  "entity": "minecraft:cow",
  "vertical_offset": "-size_y",
  "face_offset": "size_z + (size_z / 2) + parasite_height"
}

Use this style when the facehugger should sit forward from the front of the head.

Villager

{
  "entity": "minecraft:villager",
  "vertical_offset": "-(size_y / 2)",
  "face_offset": "size_z - 0.2"
}

Villager-like entities may need a slightly reduced face_offset because the fallback renderer applies a small villager-specific Z adjustment when no datapack offset exists.

Hoglin

{
  "entity": "minecraft:hoglin",
  "vertical_offset": "-(size_y / 2)",
  "face_offset": "size_z + parasite_height"
}

Larger mobs often need a more conservative vertical offset and a larger forward offset.

Modded entity

{
  "entity": "examplemod:example_beast",
  "vertical_offset": "-(size_y / 2)",
  "face_offset": "size_z + (parasite_width / 2)"
}

This only works if the host entity also has built-in EntityHeadData registered in code. The datapack entry does not define head dimensions by itself.

How the game loads entries

On resource reload, the loader reads every JSON file under:

data/<namespace>/ovomorphosis_head_offsets/*.json

For each file, it:

1. Reads the JSON object.
2. Resolves the entity ID from the entity field, or from the file path if entity is missing.
3. Looks up that entity type in the built-in entity registry.
4. Parses vertical_offset and face_offset with the offset codec.
5. Stores the result in the runtime entity offset map.

If an entry fails to load, the mod logs an error like:

Failed to load head offset <file>: <reason>

After loading, the mod logs how many entity head offset entries were loaded.

Testing workflow

1. Create or edit your JSON file.
2. Place the datapack in the world's datapacks folder.
3. Run /reload in-game.
4. Check the log for the loaded entry count or any Failed to load head offset errors.
5. Spawn the target host entity and attach a facehugger.
6. Adjust vertical_offset and face_offset until the model sits correctly.

Tuning tips

• Start with simple expressions before adding parasite-size adjustments.
• Use size_y when tuning up/down placement.
• Use size_z when tuning forward/back placement.
• Use parasite_height or parasite_width when the offset should scale with the facehugger model size.
• If a JSON file appears to load but has no visual effect, confirm that the host entity has built-in head data.
• If the entity is vanilla and the file is named after the entity, the entity field can be omitted, but including it makes the entry easier to read.

Troubleshooting

The entry does not load

Check that the file is in:

data/<namespace>/ovomorphosis_head_offsets/<entry>.json

Also check that both required fields are present:

"vertical_offset": "...",
"face_offset": "..."

The log says Unknown entity type

The entity value is not a valid registered entity ID. Confirm the namespace and path, for example:

"entity": "minecraft:cow"

or:

"entity": "examplemod:example_beast"

The entry loads but the facehugger does not move

The host may not exist in the built-in EntityHeadData table. Datapack offset entries only customize offsets for entities that already have head size/pivot data available in code.

The facehugger is too far inside the head

Increase face_offset, for example:

"face_offset": "size_z + parasite_height"

The facehugger is too high or too low

Adjust vertical_offset, for example:

"vertical_offset": "-(size_y / 2)"

or:

"vertical_offset": "-size_y"

Minimal template

{
  "entity": "minecraft:replace_me",
  "vertical_offset": "-(size_y / 2)",
  "face_offset": "size_z + parasite_height"
}