Project / what the port actually required

NeoForge 26.1.2 API notes

This SDK is further from mainline 1.21.x than the version numbers suggest, and almost every entry below cost a compile error or a crash to find. Read it before writing anything in neoforge-26.1.2/ that touches an unfamiliar Minecraft system — particularly rendering, the GUI layer, saved data, or anything posted from inside the chunk system. It is also the closest thing the project has to a map of what a future version port will have to redo.

This SDK is further from mainline 1.21.x than the version numbers suggest.

• tameWithName does not fire AnimalTameEvent. AbstractHorse.tameWithName sets the owner, sets tamed, fires the advancement trigger and broadcasts the hearts - that is all. The NeoForge event is fired by the caller: RunAroundLikeCrazyGoal calls EventHooks.onAnimalTame first and tames only if nothing cancelled it. So taming a horse your own way and calling tameWithName bare gives a horse that is tamed and owned and that no listener ever hears about. It has cost this project twice - hand-taming through CrouchFeedGoal (gap 154), then the debug stick (2026-09-11), where a stick-tamed horse filled no Breeds row and looked like a breed-registry bug. Copy the goal: if (!EventHooks.onAnimalTame(horse, player)) horse.tameWithName(player);
• EntityLeaveLevelEvent fires from inside the chunk system - never touch block state in its handler. It is posted from ServerLevel$EntityCallbacks.onTrackingEnd -> PersistentEntitySectionManager .stopTracking, which runs inside DistanceManager.runAllUpdates. Any level.getBlockState(pos) / getChunk there forces a chunk load that re-enters the same update pass and blows up with IllegalStateException: Entity is already tracked! (ChunkMap.addEntity). The owner hit this going to the horse dimension: teleporting out of the overworld unloads chunks, untracks every glowing horse in them, and GeneAbilityHandler.onEntityLeave was calling clearLight (a getBlockState) synchronously. Fixed 2026-09-05: onEntityLeave now just queues a PendingClear(dimension, pos) and a ServerTickEvent.Post drains the queue next tick (safe - not inside runAllUpdates). Same family as the applyTraitsToEntity / SCALE crash the herd work fought (see the debug-pen section); server.execute is not a safe deferral here either (it drains next to pollTask).
• ResourceLocation is now net.minecraft.resources.Identifier - same surface (withDefaultNamespace, fromNamespaceAndPath), different name.
• Horse classes moved net.minecraft.world.entity.animal.horse -> ...animal.equine (Horse, Variant, Markings, AbstractHorse).
• HorseRenderer is final. GeneticHorseRenderer extends AbstractHorseRenderer<Horse, HorseRenderState, HorseModel> and copies vanilla HorseRenderer's constructor body verbatim. Render-state stays the vanilla HorseRenderState so the copied layers type-check; createRenderState() covariantly returns the GeneticHorseRenderState subclass and every instance really is that subclass.
• getTextureLocation(S) is still the texture hook - the submit() / SubmitNodeCollector split didn't swallow it for entities.
• PlayerInteractEvent itself is not cancellable - only its subclasses are. setCanceled / setCancellationResult are declared on RightClickBlock, RightClickItem, EntityInteract and EntityInteractSpecific individually, so a shared consume(PlayerInteractEvent) helper does not compile and you write the four handlers out. Worth knowing which four: a right-click reaches exactly one of them depending on what the crosshair is over, and an item that handles only RightClickBlock + RightClickItem silently does nothing when aimed at a mob (see CustomHorseSpawnEggClient).
• An access transformer on a client-only class is fine on a dedicated server. AbstractMountInventoryScreen is @OnlyIn(Dist.CLIENT) and this mod's accesstransformer.cfg opens its mount field; runServer boots clean, with no missing-target error or warning. The field is the only reliable answer to "which horse is this inventory screen showing" - player.getVehicle() is right only while you are riding, and shift-right-clicking a tamed horse opens the same screen without mounting.
• EventBusSubscriber dropped bus() / Bus. IModBusEvent subtypes auto-route to the mod bus, everything else to the game bus.
• AttachmentType.Builder#serialize takes a MapCodec, not Codec.
• AttachmentType.builder(Function<IAttachmentHolder, T>) overload lets the default read the holder (e.g. entity.getUUID()).
• KeyMapping conflict-context ctor takes a KeyMapping.Category (a record keyed by an Identifier), not a lang key. Debug keybind reuses KeyMapping.Category.MISC.
• EntityType#create needs an EntitySpawnReason - create(level, EntitySpawnReason.COMMAND).
• DynamicTexture(NativeImage) is gone - use DynamicTexture(Supplier<String> label, NativeImage image); it takes ownership and closes the image (don't also close it). NativeImage.getPixel (x,y) / setPixel(x,y,argb) are ARGB (ARGB.fromABGR/toABGR under the hood); getWidth() / getHeight(). GeneticCoatTextureFactory builds a fresh new NativeImage(128,128,false), setPixels the composer's int[] in, and hands it to the DynamicTexture.
• Client reload listeners go through AddClientReloadListenersEvent (mod bus, fired once while Minecraft is constructed), not a RegisterClientReloadListenersEvent - that name does not exist here, and the server-side twin is the differently-prefixed AddServerReloadListenersEvent. event.addListener(Identifier, PreparableReloadListener); a mod listener sorts after every vanilla one unless you call addDependency, which is usually what you want, since the vanilla TextureManager has finished reloading by then. PreparableReloadListener.reload itself is now (SharedState, Executor taskExecutor, PreparationBarrier, Executor reloadExecutor) - the resource manager arrives inside SharedState and the profiler arguments are gone - so implement ResourceManagerReloadListener and override onResourceManagerReload(ResourceManager) rather than writing the future by hand. CoatAssetReload is the mod's only client listener.
• Serverbound packets: PacketDistributor.sendToServer -> net.neoforged.neoforge.client.network.ClientPacketDistributor. sendToPlayer / sendToPlayersTrackingEntity stayed on PacketDistributor.
• Reach the server via ((ServerLevel) player.level()).getServer() or player.level().getServer() (Level#getServer() exists; ServerPlayer#getServer() was the one that didn't resolve).
• dimension_type JSON schema changed heavily. Gone: ultrawarm, natural, piglin_safe, respawn_anchor_works, bed_works, has_raids, fixed_time, effects. New required: has_ender_dragon_fight (bool). effects -> skybox ("none" / "overworld" / "end"). Time-of-day moved to a WorldClock/Timeline registry (permanent noon would need default_clock / timelines). A stale dimension_type JSON fails RegistryDataLoader and takes down the client (ReportedException -> Stopping!) the moment a world is created - reads as "singleplayer is broken". data/horsegenetics/dimension_type/debug_pens.json is min_y: 0, height/logical_height: 512 (512 for random-Y plot headroom).
• Flat-generator dimension/debug_pens.json schema unchanged; "structure_overrides": [] disables villages/etc. It's now the_void biome + a single air layer (generates nothing - DebugPenManager builds the floor itself).
• Scoreboard.removePlayerFromTeam(name, team) THROWS when the entry is not on that team. It is written for /team leave, where membership is the precondition, and it raises IllegalStateException: Player is either on another team or not on any team rather than returning false. Ask first - scoreboard.getPlayersTeam(name) == team - or use the one-argument removePlayerFromTeam(String), which returns a boolean. The two-argument form crashed the server tick on 2026-09-12 (see coding notes); its sibling addPlayerToTeam is the forgiving one, which is what makes the asymmetry easy to miss.
• A world's spawn point is its respawn data, and a ResourceKey's id is identifier(). There is no Level#getSharedSpawnPos() any more: the world spawn is level.getLevelData().getRespawnData().pos() (LevelData.RespawnData is a record of a GlobalPos plus yaw and pitch, with pos() as the convenience). And ResourceKey#location() is now identifier(), which bites anywhere a registry key is turned into a printable id - biome.unwrapKey().map(k -> k.identifier().toString()). Both found writing the test world's spawn-biome report (DebugTestWorldHandler).
• com.mojang.authlib.GameProfile is a record - profile.name() / profile.id(), no getName().
• Attributes are Holder<Attribute>. LivingEntity#getAttributeValue( Holder<Attribute>) -> double; #getAttribute(Holder<Attribute>) -> @Nullable AttributeInstance with setBaseValue(double). Attributes. MOVEMENT_SPEED / MAX_HEALTH are holders. Horses register both by default (createBaseHorseAttributes); WATER_MOVEMENT_EFFICIENCY is not on horses, so don't rely on it.
• Ride/movement gates: Entity#isLocalInstanceAuthoritative() (public final) is the "this side simulates the movement" check - true on the controlling client for a player-ridden mob, on the server otherwise. Entity#getControllingPassenger() -> @Nullable LivingEntity. Mob#moveTo(...) was renamed snapTo(...) (same overloads; y arg must be double). No water auto-dismount anywhere in Entity / LivingEntity / Player.
• The GUI layer is retained-mode. GuiGraphics -> net.minecraft.client .gui.GuiGraphicsExtractor; screens/widgets override extractRenderState(GuiGraphicsExtractor, int mouseX, int mouseY, float) instead of render(...); text graphics.text(font, comp, x, y, argb) / centeredText(...); rects graphics.fill(x0,y0,x1,y1,argb); textures graphics.blit(Identifier, x0,y0,x1,y1, u0,u1,v0,v1). Mouse: mouseClicked(MouseButtonEvent event, boolean doubleClick) (event.x() / .y() / .button()), same for mouseReleased / mouseDragged. NeoForge ScreenEvent.Init.Post#addListener and the ScreenEvent.Render.* events (each #getGuiGraphics()) still bolt widgets/overlays onto vanilla screens. AbstractContainerScreen#getGuiLeft() / getGuiTop() are deprecated-for-removal but still work (used by HorseScreenHooks).
  • ScreenEvent.Render timing: Pre fires before the dimmed backdrop, Background after the backdrop but before the widget stratum, Post after everything. To draw a panel behind your own buttons but over the backdrop, use Background (that's what HorseScreenHooks learned the hard way - Pre gets painted over, Post covers the buttons).
  • Swallowing a keybind while a text field is focused: ScreenEvent.KeyPressed.Pre (getKeyCode() / getKeyEvent()), cancel it so the screen's keyInventory handler doesn't close the GUI; forward the key to the box yourself for backspace/arrows. CharacterTyped is a separate event, so letters still type (HorseScreenHooks.onKeyPressed).
  • Scaling GUI text: g.pose() is a Matrix3x2fStack - pushMatrix() / translate(x,y) / scale(s) / popMatrix() around a g.text(font, comp, 0, 0, argb) call scales it about (x,y) (FamilyTreeScreen.drawFitted). g.enableScissor(x0,y0,x1,y1) / disableScissor() clip everything including g.entity(...).
  • A live 3D entity in a screen: build the render state yourself (Minecraft.getEntityRenderDispatcher().getRenderer(e).createRenderState(e, 1f), then state.shadowPieces.clear(), poke LivingEntityRenderState angles) and g.entity(state, scale, translation, rot, camRot, x0,y0,x1,y1)
    • see FamilyTreeScreen.drawHorseModel, which uses a throwaway client-only Horse and injects the coat onto GeneticHorseRenderState directly (no ClientCoatCache pollution).
• SavedData is gutted to a dirty flag - no save(CompoundTag). Persistence is SavedDataType<T>(Identifier id, Supplier<T> ctor, Codec<T> codec) via SavedDataStorage#computeIfAbsent (ServerLevel#getDataStorage() per level, MinecraftServer#getDataStorage() server-global - the ancestry DB uses the server-global one, so it lands in <save>/data/ = per world).
• Block registry: DeferredRegister.createBlocks(modid) -> .registerBlock(name, Function<Properties, ? extends B>, Supplier<Properties>) - third arg is a Supplier<Properties>, not a bare Properties -> DeferredBlock<B>. ModBlocks.register(modEventBus) and ModBlockEntities.register(modEventBus) are called from the HorseGenetics constructor. No BlockItem for hay_portal (placed only by code).
• hay_portal block entity + renderer: HayPortalBlock extends BaseEntityBlock, getRenderShape -> RenderShape.INVISIBLE, newBlockEntity -> HayPortalBlockEntity extends TheEndPortalBlockEntity (subclassed only so AbstractEndPortalRenderer's T extends TheEndPortalBlockEntity bound is satisfied; its protected ctor is callable from a subclass). ModBlockEntities registers the type via new BlockEntityType<>(HayPortalBlockEntity::new, ModBlocks.HAY_PORTAL.get()). HayPortalRenderer extends AbstractEndPortalRenderer<HayPortalBlockEntity, HayPortalRenderState> for the plumbing only (facesToShow population + BER registration) - submit(...) no longer touches the End-portal shader. HayPortalRenderState extends EndPortalRenderState adds axis (from the block's AXIS state), set in an extractRenderState override.
  • Geometry: AXIS (HORIZONTAL_AXIS) is the axis the portal plane runs along (vanilla nether convention). The slab is thin along the other axis (thinAxis = X<->Z swap), inset to SLAB_MIN..SLAB_MAX (0.25..0.75) there, and only the two faces with dir.getAxis() == thinAxis are drawn - so it faces the player, not edge-on. (Getting this backwards was the "portal is sideways" bug.) emitFace(dir, from, to, ...), winding right = up x normal, corners BL/BR/TR/TL.
  • Two passes per face: opaque black (RenderTypes.entitySolid(TEXTURE), colour 0,0,0 - ENTITY_SOLID has no alpha discard + writes depth, so the sky / clouds / water can't show through) then the animated swirl (RenderTypes.entityTranslucentEmissive(TEXTURE, false), colour white, full-bright 0x00F000F0, OverlayTexture.NO_OVERLAY).
  • Texture assets/horsegenetics/textures/block/hay_portal.png - 64-wide vertical strip of 36 64x64 frames. Frame chosen by V offset; HayPortalClientAnim.currentFrame(36) advances it by wall-clock time at a speed that ramps 12 fps -> 48 fps as a client-estimated "charge" (local player standing in a hay_portal block, ramp ~10 s / decay ~2 s) rises. The .png.mcmeta (36 frame entries) is not read - kept for docs / a possible future atlas move.
  • HayPortalBlockEntity#shouldRenderFace renders a face only if the neighbour isn't another HayPortalBlock (multi-block portal shows just its outer shell). Registered in ClientSetup. Blockstate JSON: 2 axis variants -> one model that only sets a particle texture.
  • To restore the End-portal starfield: put back submitCube( state.facesToShow, RenderTypes.endPortal(), poseStack, submitNodeCollector) in submit (git history).
• The walk animation ignores Attributes.SCALE, and that is a trap for any mod that changes it. LivingEntity.calculateEntityAnimation feeds the raw world distance moved into updateWalkAnimation, which is min(distance * 4, 1) into walkAnimation.update(target, 0.4F, isBaby() ? 3.0F : 1.0F). That third argument is the only size compensation in the whole path - a foal's legs cycle 3x faster because they are short - and nothing anywhere consults the scale attribute. LivingEntityRenderer then scales the model by state.scale (= entity.getScale(), the SCALE attribute alone; getAgeScale() is separate). So a scaled entity swings ordinary-rate legs over ordinary ground with longer limbs, and its feet slide. The fix needs no mixin: divide state.walkAnimationPos in the renderer's extractRenderState after super - the phase is a monotonic accumulator, so scaling it after the fact is identical to having accumulated it slower. Leave walkAnimationSpeed alone; it is an amplitude multiplier on an angle, and an angle already scales with the model. See GeneticHorseRenderer.stretchGaitToSize.
• Mojang un-typo'd BlockBehaviour.Properties.noCollission() -> noCollision().
• Spawn point: no Level#getSharedSpawnPos(). Use level.getRespawnData().pos() (LevelData.RespawnData record: globalPos() / yaw() / pitch() + a pos() convenience).
• Cross-dimension teleport for any entity: Entity#teleportTo(ServerLevel level, double x,y,z, Set<Relative>, float yRot, float xRot, boolean resetCamera) - pulled up to Entity. Set.of() target-types to Set<Relative>. Verified 2026-08-30 for non-player entities (horses come back through the return portal).
• Leash: Mob implements Leashable; isLeashed(), getLeashHolder() (-> Entity), dropLeash() (drops the lead item), removeLeash() (no drop). Verified 2026-09-01: the roped-horse portal shortcut sends the horse through and drops the lead.
• Event hooks used this pass: LivingIncomingDamageEvent (cancelable, pre-mitigation - horse invulnerability); EntityTickEvent.Post (portal dwell timers, water riding, tamer tracking); PlayerInteractEvent.RightClickBlock (getPos(), getItemStack(), setCanceled + setCancellationResult(InteractionResult)); PlayerEvent.PlayerChangedDimensionEvent (getFrom()/getTo() -> ResourceKey<Level>), PlayerLoggedIn/OutEvent.
• PlayerInteractEvent.EntityInteract fires on both sides. For interactions that vanilla would otherwise turn into a mount (any item on a tamed horse), you must setCanceled(true) on the client too, or the client predicts the mount and rubber-bands. Do the state mutation server-only, cancel on both. (HorseInteractionHandler clock/stick.)
• Standing signs (not currently used - kept for reference): Blocks.OAK_SIGN + StandingSignBlock.ROTATION (0-15, from RotationSegment.convertToSegment(...)); text via SignBlockEntity# getFrontText() -> SignText#setMessage(line, Component) (returns a new one) -> setText(text, true) + setChanged() + sendBlockUpdated.
• Wall signs, placed from code (the stall sign does this): Blocks.OAK_WALL_SIGN.defaultBlockState().setValue(WallSignBlock.FACING, dir) (FACING is a horizontal EnumProperty<Direction>), level.setBlock(pos, state, Block.UPDATE_ALL), then ((SignBlockEntity) level.getBlockEntity(pos)) .updateText(t -> t.setMessage(line, Component), /*front=*/true) - updateText takes a UnaryOperator<SignText> and SignText.setMessage returns a new SignText (chain the calls).
• BreakBlockEvent (net.neoforged.neoforge.event.level.block): fires before removal, so event.getState() is still the block being broken; getLevel() -> LevelAccessor, getPos(), getPlayer(). Cancelable.
• SavedDataType<T>(Identifier, Supplier<T>, Codec<T>) + server .getDataStorage().computeIfAbsent(TYPE) is the server-global SavedData pattern (HorseAncestryData, StallData). ResourceKey<Level> round-trips in a codec via ResourceKey.codec(Registries.DIMENSION).
• ServerLevel#sendParticles(ServerPlayer, T, boolean overrideLimiter, boolean alwaysRender, x, y, z, int count, dx, dy, dz, double speed) - the per-player overload; alwaysRender = true defeats distance culling (used for the stall debug outline).
• Villager trades are datapack registries now. VillagerTrades.ItemListing is gone. minecraft:villager_trade (one JSON per offer: wants / gives / max_uses / xp / given_item_modifiers) and minecraft:trade_set (a HolderSet of trades plus an amount to draw) both live in RegistryDataLoader, so a mod ships them as data/<ns>/villager_trade/**.json and data/<ns>/trade_set/**.json. VillagerProfession only names five ResourceKey<TradeSet>. The upshot for modders is large: there is no trade-generation code to write and no event to hook, and a "random item" trade is a loot function in given_item_modifiers, which runs when the offer is generated - i.e. per restock, not per purchase. See the horseman.
• VillagerProfession is a built-in registry, its trades are a datapack one. The profession itself is a record registered through DeferredRegister.create(Registries.VILLAGER_PROFESSION, ...) - vanilla fills it from VillagerProfession.bootstrap - while the TradeSets it points at are JSON. Half in code, half in data, and the halves are not interchangeable.
• PoiType registration is new PoiType(Set<BlockState>, maxTickets, validRange) on Registries.POINT_OF_INTEREST_TYPE (built-in). Getting the states: block.getStateDefinition().getPossibleStates(). A job site is only acquirable once it is in the minecraft:acquirable_job_site POI tag - and datapack tags merge, so adding to a vanilla tag is additive and safe, where overriding a vanilla worldgen file is not.
• There is no data-driven way to append to a vanilla template pool, and no NeoForge StructureModifier for one (the stock modifiers only touch spawns and such). A datapack can only replace the whole template_pool file, which hard-codes today's vanilla contents into your mod and silently drops other mods' additions. The append is a runtime edit of the live StructureTemplatePool on ServerAboutToStartEvent: add to templates (the weight-expanded ObjectArrayList the generator draws from), replace rawTemplates (what the codec would re-serialise and what other mods read), and reset the lazily cached maxSize. Make it idempotent - a single-player session that quits to title and loads again reuses the same frozen pool objects, so a blind append stacks a second copy every load.
• The first access transformer in this repo lives at neoforge-26.1.2/src/main/resources/META-INF/accesstransformer.cfg. ModDevGradle 2.x auto-detects that exact path in any main-sourceset resource dir - no build.gradle change and no mods.toml entry. public widens; public-f also strips final, which is what an assignable field needs. Five lines: three on StructureTemplatePool for the pool append above, one on AbstractHorse.generateSpeed (protected static, so unreachable without extending it) so HorseSpeedFloor can ask the game for its own slowest horse instead of writing 0.1125 into prose, and one on Villager.increaseMerchantCareer for the dev-only clock shortcut that promotes a horseman a tier. That last one is worth its own note, because the alternative looks available and is not - setVillagerData(data.withLevel(n)) is public and raises the number, but re-rolling the trades to match needs updateTrades (protected) or a null offer list (offers is protected too, and getOffers only rebuilds when it is null). So a "levelled" villager keeps offering his old tier's trades, which is worse than not levelling him. Nothing in the shipped gameplay path calls it.
• A biome modifier can be code, not only data. The stock neoforge:add_spawns takes a fixed HolderSet<Biome>; a modifier whose biome list is decided at runtime (every biome a loaded breed names) is a record implementing BiomeModifier - modify(Holder<Biome>, Phase, ModifiableBiomeInfo.BiomeInfo.Builder), act only in Phase.ADD, and builder.getMobSpawnSettings().addSpawn(MobCategory, weight, new MobSpawnSettings.SpawnerData(type, min, max)) (the weight is separate from SpawnerData in 26.1.2) - whose MapCodec is registered in a DeferredRegister on NeoForgeRegistries.Keys.BIOME_MODIFIER_SERIALIZERS, then named by "type" in a data/<mod>/neoforge/biome_modifier/*.json. Biome.LIST_CODEC reads a biome list field. Modifiers run as a server starts, so anything loaded in the mod constructor is available. See world/BreedHerdsBiomeModifier.
• Opening a folder in the OS file browser is net.minecraft.util.Util.getPlatform().openPath(Path) - what the resource-pack screen's “Open pack folder” button calls. FMLPaths.GAMEDIR is .minecraft (or the instance folder), and the same on client and integrated server. The Breeds tab's button uses both.
• Day or night is Level.isBrightOutside() / isDarkOutside().
• A structure template can carry entities - it is how vanilla puts villagers in village/plains/villagers/*.nbt - and SinglePoolElement explicitly sets setIgnoreEntities(false), so jigsaw pieces place them. The entity NBT needs only {pos, blockPos, nbt:{id}}; nothing calls finalizeSpawn, so anything rolled has to be rolled by the mod on the entity's first tick. That is how the cowboy is generated.
• Jigsaw block NBT keys (for hand-baking a structure): name, target, pool, joint (aligned/rollable), final_state, selection_priority, placement_priority. In a plains village the road surface is a piece's y=0 and its street connectors sit at y=1, so a building that wants its floor level with the street puts its connector at y=1 too.
• Entity#moveTo is now Entity#snapTo (all overloads, including snapTo(BlockPos, yRot, xRot), which uses the block's bottom centre).
• Player#displayClientMessage is gone. The action bar is ServerPlayer#sendSystemMessage(Component, boolean overlay) - server-side only, so branch on instanceof ServerPlayer.
• AbstractVillager has no createAttributes() - that is on Villager. A custom merchant builds from Mob.createMobAttributes(). AbstractVillager.getOffers() assigns this.offers before calling updateTrades, so an updateTrades that calls getOffers() does not recurse - that is the vanilla pattern, not a trick.
• AttachmentType.Builder#sync(StreamCodec<? super RegistryFriendlyByteBuf, T>) syncs an attachment to tracking clients. Worth it whenever the client predicts something the attachment would forbid: right-clicking a tameable horse is client-predicted, so a server-only "this horse is not yours" check makes the player climb on and get snapped back off.
• A goal that holds Flag.MOVE at priority 0 starves every other movement goal, which is how a mob that is ridden by another mob gets steered - vanilla only hands control to a saddled mount's player passenger, so a mounted mob is otherwise dead weight. Do not also hold Flag.JUMP: that is the horse's own FloatGoal, i.e. the thing that stops it drowning.
• DoorBlock#setOpen(Entity, Level, BlockState, BlockPos, boolean) updates both halves, so only ever call it on the DoubleBlockHalf.LOWER state. There is still no "the other leaf of this double door" lookup in the SDK, but there is a reliable rule for writing one, and CowboyDoorGoal.partnerOf is it: the neighbour to either side along the wall that is a wooden door of the same FACING and the opposite HINGE. Check both perpendicular sides rather than deriving the side from the hinge - the hinge says which way a leaf swings, not which side its partner is on, and getting that backwards fails silently as a door that opens half way. Sweeping every door in a box works too and is what the deleted CowboyDoors did, but it opens doors the mob was not going through.
• DoorInteractGoal#setOpen only ever touches its own doorPos, so a double door needs the partner leaf swung by hand. Note also that DoorInteractGoal.canUse in this SDK does not consult canOpenDoors - it gates on mob.horizontalCollision plus the path - so the goal and the navigator flag are two independent switches that the caller has to keep in step. OpenDoorGoal is not usable as-is either: constructed with closeDoorAfter=false its canContinueToUse is false immediately, so it stops on the next tick and its unconditional stop() closes the door it just opened.
• PathNavigation#setCanOpenDoors gates the pathfinder, not the mob. It forwards to the NodeEvaluator, which is what decides whether a shut wooden door scores as passable or as wall. So a mob with a door-opening goal and this left off never plans a route through the door in the first place, and a mob with this on and no goal walks into the door and shoves it for ever. Both halves or neither.
• DirtPathBlock will not stay under a solid block - canSurvive is false when the block above isSolid() (a stair counts), and updateShape then schedules a tick that turns it to plain dirt. Structure placement runs Block.updateFromNeighbourShapes over the blocks it wrote, so this fires on generation: a baked structure that lays dirt_path under its own steps is laying dirt. Nothing warns you, and the NBT still says dirt_path.
• A jigsaw block never reaches the world. SinglePoolElement#getSettings adds JigsawReplacementProcessor unless keepJigsaws, and processors run before blocks are written - so final_state (defaulting to minecraft:air) is what gets placed, and the jigsaw is never briefly solid. That is what makes it safe to sit one directly above a block that cares what is over it.
• The layer of a piece that carries its jigsaw is the layer that rests on the ground. JigsawPlacement lands the child's jigsaw block at the parent connector's own world Y (targetBoxY = sourceBoxY + sourceJigsawLocalY - targetJigsawLocalY for a rigid pair, or getFirstFreeHeight - targetJigsawLocalY against a terrain_matching street). A plains street's connector sits one above its road block, so a piece whose jigsaw is in its foundation course sits one proud of the road, which is the vanilla house shape. The useful consequence: to put a block at road level, add a layer below the jigsaw's layer and lift everything else - the buildings do not move, because the jigsaw moved up with them, and the new bottom layer lands in the road's own course. The terrain beard is unaffected: it references box.minY() + groundLevelDelta, and the lift changes both by one in opposite directions.
• Loot functions register as the MapCodec itself on Registries.LOOT_FUNCTION_TYPE. Extend LootItemConditionalFunction, build the codec with commonFields(i).and(...), and note that codec() must return MapCodec<? extends LootItemConditionalFunction>, not ...LootItemFunction.
• A ModConfig.Type.SERVER file lives in the instance's config/, not in the world. It writes config/<modid>-server.toml like a common config would, and each world's serverconfig/ folder is an optional override of that path (its own readme.txt says so) rather than the place the file is created. So "edit the server config" means the instance file unless someone has deliberately put a per-world copy beside it. What still makes SERVER the right type is who wins: the server's copy is the authority and clients on it follow, which is what a setting that moves a hitbox needs (body.size).
• A config's file name is resolved with a plain Path.resolve, so it can leave config/. ConfigTracker.openConfig (FML 11.0.15) resolves the name against the config directory (or the world's serverconfig/ for a SERVER override) and setupConfigFile creates missing parents, so a name of ../phc/server.toml puts the file in .minecraft/phc/. All three of this mod's files use it (ModBreedSpecs.configFile). Seen working on a dedicated server, the file watcher included: an edit to run/phc/breed-spawning.toml was re-read live. Two consequences: a SERVER config's per-world override is then <world>/phc/server.toml, and the name must be a constant, because a SERVER config is synced to clients by file name.
• defineInList with an immutable list crashes at startup. Writing a fresh file, NeoForge probes a missing value with acceptableValues.contains(null), and List.of(...).contains(null) throws a NullPointerException - a mod-loading failure, seen. Pass a mutable list.