Forge - World generation, loading, saving

Registries for World generation, loading, saving

The registries involved in world generation are:

• Dimension: DimensionManager.registerProviderType (in conjunction with WorldProvider) can be used to add new dimensions in addition to the Overworld, Ender, and Nether.
• Terrain generation: GameRegistry.registerWorldGenerator(IWorldGenerator) � allows you to register an IWorldGenerator to generate new chunks as they are required.
• Villages: VillageRegistry contains several methods to alter the random generation of village components (huts, farms, etc).
• Biomes: There are a bunch of registries relating to Biomes that to be honest I don�t properly understand.  If you are interested, these are
  

  * GameRegistry.addBiome(BiomeGenBase).

  * BiomeManager.addSpawnBiome allows the new Biome to be used during random world generation,  .addStrongholdBiome and .addVillageBiome are used to control whether Strongholds and Villages will randomly spawn in this biome.

  * BiomeDictionary � types of Biomes (HILLS, PLAINS, etc)
• Loot Chests: ChestGenHooks is used to create new types of random loot chests (DUNGEON_CHEST, VILLAGE_BLACKSMITH, etc).
• Mob spawners: DungeonHooks addDungeonMob will let you add new mobs to the vanilla spawner.

New methods and classes

• WorldProvider- has been modified to  allow player to override many methods related to a custom world they have made
• IRenderHandlerhas been added to WorldProvider � it can be used by mods to perform a custom render of the sky or the clouds � setSkyRenderer() and setCloudRenderer(). 
• Although Forge has added a rather tempting setAdditionalProperties() method to WorldInfo, the way it has been coded means it�s not actually useful for mods to use when storing permanent data about a world.    Use world.perWorldStorage instead (used by vanilla for villages, but can be hijacked for your own purposes relatively easily).

Events         

• TickRegistry.registerTickHandler for WORLD ticks (every world update)
• TickRegistry.registerTickHandler for WORLDLOAD event (when world is loaded)
• WorldEvent.Load, .Unload, .Save

There�s an impressive pile of events related to world generation, biomes, loading and saving of chunks.  I don�t understand most of them so I�ll leave that for a later time.  Perhaps.

---

~Overview of Forge (and what it can do for you)
    Forge concepts
           Some general notes
           How Forge starts up your code (@Mod, @SidedProxy, etc) 
           Registering your classes
           Extra methods for vanilla base classes
           Events
     Forge summary - grouped by task
           Blocks
           Items
           TileEntities
           Entities
           World generation, loading, saving
           Miscellaneous - player input, rendering, GUI, chat, sounds

Forge - TileEntities

Registries

• GameRegistry.registerTileEntity to add your TileEntity�s name
• ClientRegistry.bindTileEntitySpecialRenderer (in conjuction with a TileEntitySpecialRenderer class).  The renderer is bound directly to the object�s class definition, unlike Block or Item there is no �shared ID� required.

New methods and classes

• Several new methods added around rendering and controlling object lifetime

Events

None

---

~Overview of Forge (and what it can do for you)
    Forge concepts
           Some general notes
           How Forge starts up your code (@Mod, @SidedProxy, etc) 
           Registering your classes
           Extra methods for vanilla base classes
           Events
     Forge summary - grouped by task
           Blocks
           Items
           TileEntities
           Entities
           World generation, loading, saving
           Miscellaneous - player input, rendering, GUI, chat, sounds

Forge - Miscellaneous stuff � player input, rendering, GUI, chat, sounds

Player Input

• KeyBindingRegistry � allows you to add your own keybindings to the vanilla ones � (for example some vanilla keybindings are A for left and D for right).  Your custom keybindings will appear on the options page so that the player can change them.
• MouseEvent � allows you to intercept mouse clicks and mouse movement before the vanilla code sees it.

Rendering

A lot of the custom stuff related to rendering has been covered in the other sections, however there are also quite a few other events related to rendering, listed below:

• Various events used to customise Biome-dependent rendering, such as grass colour � see BiomeEvent.
• FOVUpdateEvent (FOV = Field of View, which means how �wide� your view is)
• RenderGameOverlayEvent gets called for a whole stack of different parts of the screen overlay, such as hotbar, crosshairs, health bar, etc.  See enum ElementType in the event for more information.
• DrawBlockHighlightEvent� draw the highlight box around the block when your cursor is pointing at it
• Another bundle of Events under RenderLivingEvent and RenderPlayerEvent can be used to control the rendering of the player and other entities in quite some detail.

Graphical User Interface

I�m a bit rubbish on this section because I�ve never actually customised a GUI.  From what I can tell, there are a few forge-related additions:

• AchievementPage.registerAchievementPage lets you add your own achievement pages.
• NetworkRegistry.registerGuiHandler (using IGuiHandler) � not sure how to use this.
• GuiIngameForge � replace vanilla in-game overlays with many extra events, and also adds a large number of  flags you can change to turn rendering of HUD elements on/off � for example hotbar, crosshairs, helmet, experience bar, etc.
• GuiControlsScrollPanel� accommodates any extra key bindings you have added to the KeyBindingRegistry
• GuiOpenEvent � used to replace a GUI with your own customised version
• PlayerOpenContainerEvent� when opening a GUI container.

Chat

There are a few interesting events related to chat:

• NetworkRegistry.registerChatListener(using  IChatListener) for intercepting chat messages including commands
• NetworkRegistry.registerConnectionHandler(IConnectionHandler) which gives control over clients and players connecting to the server.
• CommandEvent
• ServerChatEvent
• ClientChatReceivedEvent

Sounds

Sounds are registered using SoundLoadEvent  instead of a registry call.  Don�t ask me why.  They are played using using vanilla methods such as SoundManager.playSound.  Some related events are

• SoundSetupEvent
• PlayBackgroundMusicEvent
• PlaySoundEffectEvent
• PlaySoundEffectSourceEvent
• PlaySoundEvent
• PlaySoundSourceEvent
• PlayStreamingEvent
• PlayStreamingSourceEvent
• PlaySoundAtEntityEvent

---

~Overview of Forge (and what it can do for you)
    Forge concepts
           Some general notes
           How Forge starts up your code (@Mod, @SidedProxy, etc) 
           Registering your classes
           Extra methods for vanilla base classes
           Events
     Forge summary - grouped by task
           Blocks
           Items
           TileEntities
           Entities
           World generation, loading, saving
           Miscellaneous - player input, rendering, GUI, chat, sounds

Forge - Entities

Forge has a lot of code related to entities.  Broadly speaking it can be grouped roughly into

• inanimate entities (minecarts, dropped items)
• animals and mobs
• the player

Registries

• RenderingRegistry.registerEntityRenderingHandler (in conjunction with a Render class).   The renderer is bound directly to the object�s class definition, unlike Blocks no shared ID is required.
• EntityRegistry.registerModEntity to add your entity to the game
• EntityRegistry.addSpawn to control how your entity spawns randomly into the world, for example if you create a new Entity called Deer and you want them to spawn randomly in the woods/forest but not in the desert. 
• DungeonHooks.addDungeonMob can be used to add your mob to mob spawners found in dungeons.
• VillagerRegistry: contains a number of methods to add trading recipes and control the spawning of different villager types.

New methods and classes

• Models: These contain a few classes related to rendering, I�m not actually sure if they�re ever used since it seems people nearly always use Techne to make new Entity rendering models and that appears to use vanilla Models only.
• IEntityAdditionalSpawnData is used to add extra info to the mod�s spawn packet � the server provides the information, and the client can read it when the entity is spawned.
• IExtendedEntityProperties - for storing extra permanent information in an Entity, i.e. information that will be saved to disk and reloaded.

Events

• EntityMinecart.registerCollisionHandler(IMinecartCollisionHandler) � superceded
• GameRegistry.registerPlayerTracker - for tracking players � login, logout, respawn, dimension change.
• WorldEvent.PotentialSpawns � control which entities are spawned in which location.
• TickRegistry.registerTickHandlerfor PLAYER event � whenever an EntityPlayer�s onUpdate is called.

There is a whole stack of other events related to entities that I�m not going to list in detail  - look in the events package if you want to browse through them.  They can be broadly split into several types:

• Rendering events
• Change of state � eg spawning and despawning, death, picking up, discarding, throwing, use by player
• Interactions with the player, other entities, items, especially attack, damage, targeting
• Player actions � eg flying, falling, sleeping, left or right clicking

Personally I find it sometimes takes me a few tries to find the right event.  There is often some overlap between the different events but subtle differences too.  Usually boils down to guesswork from looking at the vanilla code, plus a bit of trial and error.

---

~Overview of Forge (and what it can do for you)
    Forge concepts
           Some general notes
           How Forge starts up your code (@Mod, @SidedProxy, etc) 
           Registering your classes
           Extra methods for vanilla base classes
           Events
     Forge summary - grouped by task
           Blocks
           Items
           TileEntities
           Entities
           World generation, loading, saving
           Miscellaneous - player input, rendering, GUI, chat, sounds

Forge - Blocks

An overview of the Forge code related to Blocks.

Registries

• GameRegistry.registerBlock to register your block and (optionally) associate it with an ItemBlock.  If you don�t provide an ItemBlock, it will make a default one itself and register it for you.  If you provide an ItemBlock, you don�t need to register the ItemBlock yourself separately.  GameRegistry.findBlock can be used to retrieve the block corresponding to a given name.
• RenderingRegistry.registerBlockHandler (in conjunction with an ISimpleBlockRenderingHandler class).  RenderingRegistry uses a unique renderID, returned by the class�s getRenderType, to find the renderer with the matching .getRenderID() method.   RenderingRegistry.getNextAvailableRenderId() is useful for getting a unique ID for the linked classes to share.  See here for more information.
• MinecraftForge.addGrassPlant  (and .addGrassSeedfor the corresponding Item) are used to add new types of grass.
• MinecraftForge has a several methods used to add new tools and control their effectiveness against different blocks, in particular setToolClass and setBlockHarvestLevel.
• LanguageRegistry.addNameForObject � allows you to add a displayed name for your Blocks.  Apparently it�s better to use a Language Pack instead of this registry.  I haven�t tried those yet so I don�t know.
• ChestGenHooks is used to control the spawning of loot chests during world generation.  See the World generation section.

Utility functions

• RotationHelper: a couple of functions to help rotate vanilla blocks to face the desired direction (eg piston, doors, etc), convert from block�s metadata to a standard �direction value�.

New methods and classes

• Block has many methods added to let mods change behaviour more easily � ladder, fire, tileentities, beds, harvesting, leaves interaction, explosion interaction, plant interactions, redstone, and a few more.   They are defined after the comment in the Block code
  

  /*===========Forge Start ========*/.
• IPlantableinterface for plants
• IShearableinterface for blocks which can be �shorn� by shears � eg like tallgrass or vines
• Fluids:  A variety of classes to let you define your own fluids (like lava and water) and control their behaviour; comprised of BlockFluidBase, BlockFluidClassic, Fluid and FluidStack.

Events

• BreakEvent � when a block is broken
• DrawBlockHighlightEvent� draw the highlight box around the block when your cursor is pointing at it
• PlayerInteractEvent� among other things - when a player left-clicks a block
• HarvestDropsEvent� when a block is harvested
• HarvestCheck � can the player break this block with this tool?
• BreakSpeed � speed of breaking this block with this tool
• SaplingGrowTreeEvent
• BonemealEvent � when bonemeal is used on a plant
• Various FluidEvents related to the Forge Fluids classes

---

~Overview of Forge (and what it can do for you)
    Forge concepts
           Some general notes
           How Forge starts up your code (@Mod, @SidedProxy, etc) 
           Registering your classes
           Extra methods for vanilla base classes
           Events
     Forge summary - grouped by task
           Blocks
           Items
           TileEntities
           Entities
           World generation, loading, saving
           Miscellaneous - player input, rendering, GUI, chat, sounds

Forge - Items

An overview of the Forge code related to Items.  Note � EntityItems (i.e. Items which have been thrown onto the ground) are not covered here, see Entities instead.

Registries

• GameRegistry.registerItemis used to register your item.  In some cases, you may have a single Item which represents different things depending on the damage value � for example ItemCloth (wool), which uses the damage value to represent the colour of the wool.  In this case use GameRegistry .registerCustomItemStackto register the ItemStack instead of the Item.
  In general, for an ItemBlock (Item which corresponds to a Block, eg ItemLeaves and BlockLeaves) you shouldn�t register it separately, instead you should supply it to GameRegistry.registerBlock when you register the corresponding Block.
  GameRegistry.findItem can be used to find the Item corresponding to a given name.
• MinecraftForgeClient.registerItemRenderer (in conjunction with an IItemRenderer class). MinecraftForgeClient binds the IItemRenderer to the item ID.
  There is a special registry for rendering armour. The vanilla code is restricted to a predetermined list of armour types (�prefixes�) - "leather", "chainmail", "iron", "diamond", "gold". You can add your own (eg �lycra�) using
  RenderingRegistry.addNewArmourRendererPrefix
  When an entity wearing your armour is rendered, it will then use a texture of the form lycra_boots.png, lycra_leggings.png, etc. (This can also be achieved using Item.getArmorTexture, which is probably a better way to be honest).
• MinecraftForge. addGrassSeed(and . addGrassPlant  for the corresponding Block) are used to add new types of grass.
• MinecraftForge has a several methods used to add new tools and control their effectiveness against different blocks, in particular setToolClass and setBlockHarvestLevel.
• LanguageRegistry.addNameForObject� allows you to add a displayed name for your Items and ItemStacks.  Apparently it�s better to use a Language Pack instead of this registry.  I haven�t tried those yet so I don�t know.
• GameRegistry.addRecipe (shaped, shapeless) lets you add custom recipes for crafting items.
• GameRegistry.addSmelting, GameRegistry.registerFuelHandler(with IFuelHandler) � for controlling how furnaces make use of your Items- allows you to add custom smelting recipes (eg smelting iron ore to ingots) or add custom fuels (in addition to coal, wood, etc).

When registering crafting recipes or smelting recipes, use OreDictionary.WILDCARD_VALUE for ItemStacks where any damage value will match (eg for a recipe using wool (ItemCloth) where any colour can be used).

Utility functions

• EnumHelper (and EnumHelperClient for use on client-side only)� can be used to add extra elements to the various vanilla enums, for example vanilla EnumToolMaterial which has WOOD, STONE, IRON, EMERALD (diamond), and GOLD, to which you could add for example OVERCOOKED_SPAGHETTI.

New methods and classes

• Item has many methods added to let mods change behaviour more easily � when dropped, used (eaten), used on entities or blocks, rendering, armor, potions, enchantment, They are defined after the comment in the Item code
  

  /*===========Forge Start ========*/.
• ISpecialArmor � ItemArmor classes call the functions in this interface when calculating damage reduction � if you define your Item to implement ISpecialArmor, the appropriate methods on your item will be called when damage reduction is being calculated.
• IPlantableinterface for plants
• Ores: OreDictionary, ShapedOreRecipes, ShapelessOreRecipes - As far as I can tell, this lets you make recipes using ores provided by other mods, in particular BuildCraft.  Some vanilla examples of ore are iron, stone, wood.

Events

• GameRegistry.registerPickupHandler� when player picks up an item, superceded by EntityItemPickupEvent.
• ItemTossEvent  - when the item is about to enter the world (discarded by player)
• FillBucketEvent � when a bucket is filled (click on water, lava etc) or emptied.
• ItemTooltipEvent � when your cursor is hovering over an item, to let you customise the ToolTip text that appears.
• PlayerDestroyItemEvent� whenever an item is destroyed / used up.
• UseHoeEvent � player uses a hoe tool
• OreRegisterEvent
• GameRegistry.registerCraftingHandler(ICraftingHandler) for when an item is crafted or smelted.
• PotionBrewedEvent

---

~Overview of Forge (and what it can do for you)
    Forge concepts
           Some general notes
           How Forge starts up your code (@Mod, @SidedProxy, etc) 
           Registering your classes
           Extra methods for vanilla base classes
           Events
     Forge summary - grouped by task
           Blocks
           Items
           TileEntities
           Entities
           World generation, loading, saving
           Miscellaneous - player input, rendering, GUI, chat, sounds

Overview of Forge (and what it can do for you)

The main purpose of Forge is to allow multiple mods to be installed without interfering with each other. It does this in a few ways;

1. providing a standard mechanism to load and initialise mods.
2. providing ways for your mod to interact with the vanilla minecraft code without you having to modify or overwrite any of the vanilla code.
3. allowing your mods �assets� (custom sounds, textures, etc) to be stored in your mod�s zip file instead of in the vanilla assets folder.

Loading and Initialising your Mod

Forge achieves the first objective by searching for your mod in the mods folder. When it finds your mod, it uses a technique called reflection to discover which of your mod�s methods it should call to initialise it. During initialisation, your mod then calls a number of forge methods to instruct forge on how to interact with your mod�s code.  More details below.

The load and initialisation sequence is covered in some more detail here.
Forge also uses a file called Mcmod.info (if provided by your mod) to display a description and other information about your mod.

Avoiding the need to modify vanilla code

The three key ways that Forge achieves this second objective are:

1. providing a number of Registries where you can register your new Blocks, Items, Recipes, etc, so that the vanilla code can interact with them.
2. adding extra methods to the vanilla base classes (eg Block), so that your code can override them when you extend the base class � i.e. using inheritance to make vanilla code call your new code.
3. providing a multitude of �events� that your mod can register its interest in, for example �call myModTickHandler every 1/20 of a second� or �call mySleepHandler� every time a player sleeps in a bed.

Loading your mod�s assets

Forge adds your mod to the list of places that minecraft searches when it�s looking for assets. The most confusing part of the assets folder is that you need to know where to put it! When your mod is packaged up as a zip and placed in the mods folder, this is easy.

Basic structure of the zip file for an example mod "speedytools".

When you�re debugging, it�s a bit harder. You need to find the base path that Forge looks in. To be honest I�m not sure what this is supposed to be. Here is how I figured it out for my setup:
http://www.minecraftforge.net/forum/index.php?topic=11963.0
If you're using Eclipse (which I'm not), apparently you should put your assets into 
\src\minecraft\
 in order to get them copied into the right place during debugging.

Based on painful experience I'd suggest you use lowercase for your modid, folder names, and filenames. This will avoid subtle problems where (eg) textures are loaded ok during testing but can�t be found once packaged up into a zip (zip files are case-sensitive, windows folders aren�t).

For those who are interested - FMLFileResourcePack and FMLFolderResourcePack are the two classes that Forge uses to represent your mod assets, i.e. textures, sounds, etc - either as a file (zip) or a folder respectively. When minecraft goes looking for (eg) a texture such as �mymod:myawesometexture.png�, it uses �mymod� to identify the correct FML Resource Pack and pull the correct data out.

---

~Overview of Forge (and what it can do for you)
    Forge concepts
           Some general notes
           How Forge starts up your code (@Mod, @SidedProxy, etc) 
           Registering your classes
           Extra methods for vanilla base classes
           Events
     Forge summary - grouped by task
           Blocks
           Items
           TileEntities
           Entities
           World generation, loading, saving
           Miscellaneous - player input, rendering, GUI, chat, sounds