ChaoticKarma/API Modding Guide

This guide is meant to help when starting out with minecraft modding using the ChaoticKarma API. It is recommend to have at last some basic Java knowledge before starting, but everything in here should be possible without. For advanced programmers this guide will likely be far too easy.

General
The class, KarmaRegistry, allows some basic interactions with the API. It allows the modder to register various things into the API, for use by the mod. In most cases, things must first be registered before they can actually be used. Registration should happen in the Initialization phase in pretty much every scenario.

Mob Ignorance
The class, MobIgnoranceRegistry, allows for adding entities into the different lists of entities ignored by certain levels.

Game events
ChaoticKarma adds a game event, known as the KarmaUpdateEvent. This event is posted to the Minecraft Forge event bus every time any player gains or loses karma. There are actually two different kinds of KarmaUpdateEvents: one that happens when the player naturally gains or loses karma, and one that happens when the player uses the Karma Set command to manually set their karma to a specific value.

The KarmaUpdateEvent has the following fields:
 * previousAmount : The amount of karma that the player had before the event.
 * JavaDocs: The previous karma level that the player had. In other words, the amount BEFORE the event.
 * updateAmount : The amount of karma being added or taken from the player. Since this is an Integer and not an int, it can be null. This happens when the other kind of event is posted.
 * JavaDocs: The amount of karma being added to the player. Is null if updated through the command. Code expecting null.
 * newAmount : The new amount of karma that the player will have. This is essentially.
 * JavaDocs: The new amount of karma, or previousAmount + updateAmount.
 * player : The player whose karma is being updated.
 * JavaDocs: The player that the karma is being applied to.

Events
Events can be added by creating classes that extend either KarmaEventPositive or KarmaEventNegative accordingly. Do not extend or use KarmaEvent, or implement IKarmaEvent. These APIs aren't really useful, and will result in reinventing the wheel.

In the main constructor of the class that extends one of the event classes, the chance and required level should be set as follows:

The setRequiredKarmaLevel and setKarmaChance methods are fairly self-explanatory. The former will set the karma level needed in order for the event to occur. If the event is negative, it will need to be less than this number, and if the event is positive, it will need to be greater than this number. The setKarmaChance method will set the chance of this event happening. Typically, for somewhat rare events, chances above 1,000 are used. The chance is 1/x where x is the number set.

In order to actually implement an event, the doEvent method needs to be overridden. It should always start with a check to see if the playerHasEnoughKarma. doEvent gives the modder an instance of the player as well as the world.

Events need to be registered in the KarmaRegistry with either registerPositiveEvent or registerNegativeEvent.

Events occur during the LivingUpdateEvent on the Minecraft Forge event bus.

Perks
Perks can be added by creating classes that extend either KarmaPerkPositive or KarmaPerkNegative accordingly. the "Negative" and "Positive" refer to the type of karma needed, and not the type of effect it adds. Do not extend or use KarmaPerk, or implement IKarmaPerk. These APIs aren't really useful, and will result in reinventing the wheel.

Since perks need a little less restriction, they can be registered to the Minecraft Forge event bus when registering with KarmaRegistry.

In the main constructor of the class, the required karma level should be set with setRequiredKarmaLevel, just like with events. After that, the modder can subscribe to any events, or do anything else they need to give the player the perk.

Perks need to be registered in the KarmaRegistry with registerPositivePerk or RegisterNegativePerk. Each perk has its own string ID, of which the convention should be followed: "ModName-PerkName". Setting the third parameter, isEventHandler to true will register that perk onto the Minecraft Forge event bus. Currently, it is not possible to register it on the FML common bus.