Skip to content

Adding a custom portal

Jump to bottom
Pedro270707 edited this page Jul 20, 2026 · 8 revisions

There are two ways to immediately add a portal to your mod:

The lazy way

You can use SimplePortalBuilder in your mod's initialization to build your portal and register it. This is a red Nether portal to the End:

SimplePortalBuilder.create()
        .ignition(Items.EMERALD)
        .ignition(Blocks.EMERALD_BLOCK)
        .frame(Blocks.OBSIDIAN)
        .color(0xFF0000)
        .fromDimension(LevelStem.OVERWORLD)
        .toDimension(LevelStem.END)
        .register(Identifier.fromNamespaceAndPath("example", "end_portal"));

This returns a ResourceKey<Portal>. Ideally you should store that in a public static final field like this:

public static final ResourceKey<Portal> END_PORTAL = SimplePortalBuilder.create()
        .ignition(Items.EMERALD)
        .ignition(Blocks.EMERALD_BLOCK)
        .frame(Blocks.OBSIDIAN)
        .color(0xFF0000)
        .fromDimension(LevelStem.OVERWORLD)
        .toDimension(LevelStem.END)
        .register(Identifier.fromNamespaceAndPath("example", "end_portal"));

This is the method used by Deeper and Darker, and is also the closest to Custom Portal API.

The data-driven way

If you want to use JSON, you can create a JSON file under data/<namespace/portals/<path>.json. This JSON file has the following fields:

  • image: The root object.
    • image generator: (optional, defaults to none) The portal generator.
    • image tester: (optional, defaults to none) The portal tester.
    • image test_validity_after_generation: (defaults to true) Determines whether to test if the portal should be checked after generation (like a Nether portal) or if it should ignore the tester after being created (like the End portal).
    • image travel_time: (optional, defaults to 80 in Survival mode and 0 in Creative mode) Determines the time in ticks inside the portal until travel actions are triggered.
      • image game_modes: Travel time for each game mode.
        • image: Travel time in ticks for this game mode. The key is the game mode (survival, creative, adventure, spectator, or custom game modes).
      • image non_player: Travel time for entities which are not players (i.e., without game modes).
      • image default_time: Default travel time for game modes not specified.
    • image enter_actions: (optional, defaults to empty) Actions triggered immediately upon entering the portal.
      • image: A portal action.
    • image travel_actions: (optional, defaults to empty) Actions triggered after the travel time has passed.
      • image: A portal action.
    • image tick_actions: (optional, defaults to empty) Actions triggered every tick the portal is active.
      • image: A portal action.
    • image random_tick_actions: (optional, defaults to empty) Actions triggered on random ticks.
      • image: A portal action.
    • image animation_tick_actions: (optional, defaults to empty) Actions triggered on animation ticks.
      • image: A portal action.
    • image spectators_can_use: (defaults to match vanilla portal) Determines whether spectators can right-click the portal to travel.

Clone this wiki locally