Custom Actions with Items

Sometimes it desirable to make the tool or weapon in your hand do something different from the default behavior.  You can do this for either the left or right mouse click.  The left mouse click is usually used to hit some other entity, and the method is appropriately named hitEntity().  Here is some example code from the RedDiamondWand that is included in the code on GitHub. 

@Override
public boolean hitEntity(ItemStack itemstack, 
       EntityLivingBase target, EntityLivingBase player){
    if(!target.worldObj.isRemote){
        if(target instanceof EntityMob){
            target.motionY = 2.5;
            return true;
        }
        else { 
            // need to recast to get the subclass functionality
            // original code should have used an interface instead
            EntityPlayer entityPlayer = (EntityPlayer) player;
            entityPlayer.addChatMessage(
                "This only works on monsters");
        }
    }
    return false;
}

What this will do is the change hit action of the wand to throw a monster up in the air and let the horrible beast fall to its death.  If however, if the entity is not a monster, then it will send a message to the player telling them it only works on monsters.  Notice, that the action is wrapped in an if statement to ensure that it only happens on the server side.  It will return true if an action was taken, otherwise it returns false.  

The right mouse click is usually used to use some function on an item, and the method is named onItemRighClick().

@Override
public ItemStack onItemRightClick(ItemStack itemstack, 
        World world, EntityPlayer entityplayer) {
    itemstack.damageItem(10, entityplayer);
    if (!world.isRemote) {
        Vec3 look = entityplayer.getLookVec();
        EntityWitherSkull witherSkull = new 
            EntityWitherSkull(world, 
            entityplayer, 1, 1, 1);
        witherSkull.setPosition(
            entityplayer.posX + look.xCoord * 5,
            entityplayer.posY + look.yCoord * 5,
            entityplayer.posZ + look.zCoord * 5);
        witherSkull.accelerationX = look.xCoord * 0.1;
        witherSkull.accelerationY = look.yCoord * 0.1;
        witherSkull.accelerationZ = look.zCoord * 0.1;
        world.spawnEntityInWorld(witherSkull);
    }
    return itemstack;
}

What this will do is the change use action of the wand to throw a wither skull at whatever the player is looking at, and of course the wither skull will explode.  Notice, that the use action is wrapped in an if statement to ensure that it only happens on the server side. 

By overriding these two methods, you will be able change the action that happens with both the left and right mouse clicks.  These are just examples, and should give you an idea of what is possible.