Minecraft Forums

package iad4m;

import net.minecraft.block.Block;
import net.minecraft.block.material.Material;
import net.minecraft.item.Item;
import net.minecraft.world.biome.BiomeGenBase;
import net.minecraft.world.biome.BiomeGenDesert;
import net.minecraftforge.common.DimensionManager;
import cpw.mods.fml.common.Mod;
import cpw.mods.fml.common.Mod.Init;
import cpw.mods.fml.common.event.FMLInitializationEvent;
import cpw.mods.fml.common.network.NetworkMod;
import cpw.mods.fml.common.registry.GameRegistry;
import cpw.mods.fml.common.registry.LanguageRegistry;
import iad4m.blocks.*;
import iad4m.dimensions.BiomeGenMars;
import iad4m.dimensions.WorldProviderMars;


@Mod(modid = iAd4m.modid, name = "iAd4m", version = "0.1")
@NetworkMod(clientSideRequired = true, serverSideRequired = false)
public class iAd4m
{
public static final String modid = "iAd4m";

public static Block marsGrass;
public static Block marsPortal;

public static int marsid = -20;

public static final BiomeGenBase mars = new BiomeGenMars(25);

@Init
public void load(FMLInitializationEvent event)
{
marsGrass = new MarsGrass(3000, Material.grass).setUnlocalizedName("marsGrass");
marsPortal = new MarsPortal(3001).setUnlocalizedName("marsPortal");

GameRegistry.registerBlock(marsGrass, modid + (marsGrass.getUnlocalizedName().substring(5)));
GameRegistry.registerBlock(marsPortal, modid + (marsPortal.getUnlocalizedName()));

LanguageRegistry.addName(marsGrass, "Mars Grass");
LanguageRegistry.addName(marsPortal, "Mars Portal");

DimensionManager.registerProviderType(marsid, WorldProviderMars.class, true);
DimensionManager.registerDimension(marsid, marsid);
}
}

Version 1.6.1 (MC 1.3.2) (current version)
- Updated to Minecraft 1.3.2.
- Moved block addition/removal hooks to WorldServer so that the API no longer edits Chunk; now use DimensionChunk for terrain generation that exceeds 128 blocks of height, or for any terrain generation if you're somehow not using ModLoader or Forge.

Version 1.6 (MC 1.3.1) (client download | server download)
- Updated to Minecraft 1.3.1; some fairly major infrastructural changes occurred as a result.
- Dropped ModLoader and ModLoaderMP as dependencies; although most modders will still need ModLoader or Forge for now, technically no other mod is required for Dimension API to run.
- Integrated compatibility patches for ModLoader, ModLoaderMP, and Forge (partially, since it was not yet updated at the time of this version's release) into the API; there will no longer have to be a separate Forge patch.
- Added respawning in non-overworld dimensions to the server.
- Added an option to override respawning completely (per dimension) with a custom method.
- Added method descriptions to some of the API's most important source files, as well as markers where it edits vanilla code.
- Fixed a bug where decompiling the API would produce errors in GenLayerDimension.java.
- Fixed a bug where server-side biome generation behaved weirdly.

Version 1.5.1 (MC 1.2.5) (client download | server download | Forge client)
- The API now edits one fewer class on both the client and server; no other changes.

Version 1.5 (MC 1.2.5) (client download | server download)
- Added support for easily including multiple biomes in a custom dimension; several different types of biomes can be generated (major, minor, border, ocean, river, and miscellaneous for other types). Note that biome temperatures are currently buggy in multiplayer.
- Added a hook to intercept the addition and removal of a block from the world.
- Added a hook to intercept the right-clicking of an item.
- Allowed the Teleporter class to vary depending on the dimension from and to which the player is teleporting.
- Added a hook called before and one called after the player is teleported to and from a dimension, as well as (for the client) when the player is teleporting in the process of respawning.
- Made the onItemUse method in IItemUse more appropriate for utilization as a block placement intercept.
- Finally fixed a bug where the Nether portal animation would display when walking out of a custom portal, and the custom portal animation would display for the Nether portal.

Version 1.4 (MC 1.2.5) (client download | server download | Forge client | Forge server)
- Fixed a bug where a modded portal overlay would sometimes display instead of the Nether portal overlay.
- Removed the buggy implementation of infinite sprites; it just wasn't good enough.

Version 1.3 (MC 1.2.4) (client download | server download | Forge client | Forge server)
- Added support for a custom version of RenderGlobal by dimension.
- Added custom save folder names.
- Added adjustable terrain height per dimension. (256 vs. 128 blocks)
- Added support for overriding a texture file that isn't the terrain.png for custom animated portal textures.
- Added adjustable limit to the height at which portals can spawn when using TeleporterCustom.
- Added a buggy, experimental block/item sprite API (to add custom sprite sheets without using any terrain indices) as a workaround until Jeb adds this feature to the game.

Version 1.2 (MC 1.2.3) (client download | server download)
- Added a custom ingame screen overlay hook, useful especially for displaying a boss's health.
- Added an easy way to create new Teleporters if the portal's structure follows Nether portal pattern.
- Added an easy way to create custom portal particles like the Nether portal's.
- Added mod_ files so that the API is acknowledged by ModLoader. These don't do anything other than give the version number.
- Fixed a Minecraft bug where block IDs above 127 would crash the game when part of the terrain generation.

Version 1.1 (MC 1.2.3) (download - client/server, Forge version)
- Updated server.
- Fixed a bug where the portal would start triggering again immediately after the player arrived in a dimension.

Version 1.1, pre-release 1 (MC 1.2.3) (download - client/server)
- Added an extremely easy way to register a modified (differently-colored) Nether portal texture.
- Added support for custom portal overlays; now your portal texture (or actually any block's texture) can be displayed when the player is about to teleport instead of the Nether portal's texture.
- Added the ability to respawn the player in another dimension after dying in your dimension.
- Restructured teleportation triggering; now teleportation can be triggered by just about anything by implementing the ISpecialTeleportation interface.
- Added a hook that is called every time an item is used or a block is placed, to allow modders access to these events (for portal activation and such) by implementing the IItemUse interface.
- Custom dimensions can now have the End's sky texture.

Version 1.0 (MC 1.1.0) (download - client/server)
- First release

Firstly, you can get the sources for this API here (currently v1.6.1, alternate download here). If you're using Forge, you can get the patched sources here (alternate download here). You can merge the src folder in the download with the src folder within your MCP directory to install (but delete the minecraft_server folder if you aren't modding the server). Note that the field/method names in my or your sources may be outdated, so there is a risk of recompile errors.

-- I am currently working on an overhaul of the sample dimension to use more of the API's features; the sources for the sample dimension are outdated but will only produce a couple of (easily-fixable) errors in MCP. --
I have made a very basic example dimension as a sort of tutorial (now for both client and server!); click here to download the sources for it. Screenshot:

You must do three things specially for this mod; otherwise you only need to create a dimension normally (with a ChunkProvider, Teleporter, possibly a WorldChunkManager, etc.):

1. Make a WorldProvider that extends WorldProviderBase; you can utilize the many render-related hooks that I have created via your WorldProvider (look in WorldProviderBase to see them), but technically you are only required to give your dimension an ID number.

2. Register your dimension in your mod_ file, within "public mod_Example." All you need to do is say "DimensionAPI.registerDimension(new WorldProviderExample())" DO NOT put this in load().

3. Create a custom block (or item) that teleports you to your dimension (a portal, basically). You need to make the block's file extend BlockPortalBase (or ItemTeleporterBase), and fill in all the required (abstract) fields.

An example of a custom WorldProvider using some of the API's hooks:

package net.minecraft.src;

public class WorldProviderExample extends WorldProviderBase
{
	public WorldProviderExample()
	{
	}

	//required:
	public int getDimensionID()
	{
		return 100;
	}

	//not required:
public boolean renderClouds()
	{
		return false;
	}

	public boolean renderVoidFog()
	{
		return true;
	}

	public float setSunSize()
	{
		return 3.0F;
	}

	public float setMoonSize()
	{
		return 0.5F;
	}

	public String getSunTexture()
	{
		return "/example/sunRed.png";
	}

	public String getMoonTexture()
	{
		return "/example/moonGreen.png";
	}

	public boolean renderStars()
	{
		return false;
	}

	public boolean darkenSkyDuringRain()
	{
		return false;
	}

	public String getRespawnMessage()
	{
		return "Apparently this dimension is too tough for you ;)";
	}

//required by MC:
public void registerWorldChunkManager()
	{
		worldChunkMgr = new WorldChunkManagerExample(worldObj);
	}
	
	public IChunkProvider getChunkProvider()
	{
		return new ChunkProviderExample(worldObj, worldObj.getWorldSeed());
	}
}

An example of a custom portal block:

package net.minecraft.src;

import java.util.ArrayList;
import java.util.List;

public class BlockPortalExample extends BlockPortalBase
{
	public BlockPortalExample(int i, int j)
	{
		super(i, j, Material.portal);
	}

	//required:
	public WorldProviderBase getDimension()
	{
		return new WorldProviderExample();
	}

	public Teleporter getTeleporter()
	{
		return new TeleporterExample()
	}

	public String getEnteringMessage()
	{
		return "Entering the Example Dimension";
	}

	public String getLeavingMessage()
	{
		return "Leaving the Example Dimension";
	}

	//not required:
	public boolean isPortalImmediate()
	{
		return false;//does have a delay
	}

	public boolean displayPortalAnimation()
	{
		return true;//displays Nether portal animation
	}

	public List canTeleportFromDimension()
	{
		ArrayList arraylist = new ArrayList();
		arraylist.add(Integer.valueOf(0));//player can teleport from overworld to this dimension
		arraylist.add(Integer.valueOf(-1));//player can teleport from Nether to this dimension
		return arraylist;
	}

	public int returnsPlayerToDimension()
	{
		return -1;//returns player to the Nether
	}

	public double getDistanceRatio()
	{
		return 0.2D;//slow travel
	}

	public int getPortalDelay()
	{
		return 150;//default
	}

	public Achievement triggerAchievement()
	{
		return mod_Example.exampleAchievement;//displays upon player's arrival in the dimension
	}
}

As you can see, all the method names are pretty self-explanatory. Note that you do not have to change anything related to this API when porting your dimension to multiplayer, although you might want to get rid of any references to the rendering hooks in your WorldProvider as they are unnecessary in multiplayer.

I take requests for hooks/features to be added to the API, as long as they don't edit any more core class files than the API already does (I'll consider such hooks only if they're really huge, useful, and unique).

One last thing... I know how annoying it can be to lead people to a dozen different downloads just for one mod, so I give permission for modders who use this API to include it in their downloads. I only request that you mention your utilization of the API somewhere in your mod's post.

This tutorial is created by TheInstitutions (go subscribe to his channel!). He's already made an updated version for 1.3.1:

This API is both open source and public domain. You have permission to redistribute the files from this mod, but I prefer that you give me some credit if you do so. You can incorporate any part of my code into your mod, overwrite any of my files, make patches between this and other mods without my permission, update the mod yourself if I discontinue it, etc.