icbm/src/main/java/dan200/computercraft/api/turtle/ITurtleAccess.java

/**
 * This file is part of the public ComputerCraft API - http://www.computercraft.info
 * Copyright Daniel Ratcliffe, 2011-2015. This API may be redistributed unmodified and in full only.
 * For help using the API, and posting your mods, visit the forums at computercraft.info.
 */

package dan200.computercraft.api.turtle;

import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.lua.LuaException;
import dan200.computercraft.api.peripheral.IPeripheral;
import net.minecraft.inventory.IInventory;
import net.minecraft.nbt.NBTTagCompound;
import net.minecraft.util.ChunkCoordinates;
import net.minecraft.util.Vec3;
import net.minecraft.world.World;

/**
 * The interface passed to turtle by turtles, providing methods that they can call.
 * This should not be implemented by your classes. Do not interact with turtles except via this interface and ITurtleUpgrade.
 */
public interface ITurtleAccess
{
	/**
	 * Returns the world in which the turtle resides.
	 * @return the world in which the turtle resides.
	 */
	public World getWorld();

	/**
	 * Returns a vector containing the integer co-ordinates at which the turtle resides.
	 * @return a vector containing the integer co-ordinates at which the turtle resides.
	 */
	public ChunkCoordinates getPosition();

    /**
     * TODO: Document me
     */
    public boolean teleportTo( World world, int x, int y, int z );

	/**
	 * Returns a vector containing the floating point co-ordinates at which the turtle is rendered.
	 * This will shift when the turtle is moving.
	 * @param f The subframe fraction
	 * @return a vector containing the floating point co-ordinates at which the turtle resides.
	 */
	public Vec3 getVisualPosition( float f );

    /**
     * TODO: Document me
     */
    public float getVisualYaw( float f );

	/**
	 * Returns the world direction the turtle is currently facing.
	 * @return the world direction the turtle is currently facing.
	 */
	public int getDirection();

    /**
     * TODO: Document me
     */
    public void setDirection( int dir );

    /**
     * TODO: Document me
     */
	public int getSelectedSlot();

    /**
     * TODO: Document me
     */
    public void setSelectedSlot( int slot );

    /**
     * Sets the colour of the turtle, as if the player had dyed it with a dye item.
     * @param dyeColour 0-15 to dye the turtle one of the 16 standard minecraft colours, or -1 to remove the dye from the turtle.
     */
    public void setDyeColour( int dyeColour );

    /**
     * Gets the colour the turtle has been dyed.
     * @return 0-15 if the turtle has been dyed one of the 16 standard minecraft colours, -1 if the turtle is clean.
     */
    public int getDyeColour();

    /**
     * TODO: Document me
     */
    public IInventory getInventory();

    /**
     * TODO: Document me
     */
    public boolean isFuelNeeded();

	/**
	 * TODO: Document me
	 */
	public int getFuelLevel();

    /**
     * TODO: Document me
     */
    public void setFuelLevel( int fuel );

    /**
     * TODO: Document me
     */
    public int getFuelLimit();

    /**
	 * Removes some fuel from the turtles fuel supply. Negative numbers can be passed in to INCREASE the fuel level of the turtle.
	 * @return Whether the turtle was able to consume the ammount of fuel specified. Will return false if you supply a number
	 * greater than the current fuel level of the turtle.
	 */
	public boolean consumeFuel( int fuel );

    /**
     * TODO: Document me
     */
    public void addFuel( int fuel );

    /**
     * Adds a custom command to the turtles command queue. Unlike peripheral methods, these custom commands will be executed
     * on the main thread, so are guaranteed to be able to access Minecraft objects safely, and will be queued up
     * with the turtles standard movement and tool commands. An issued command will return an unique integer, which will
     * be supplied as a parameter to a "turtle_response" event issued to the turtle after the command has completed. Look at the
     * lua source code for "rom/apis/turtle" for how to build a lua wrapper around this functionality.
     * @param command an object which will execute the custom command when its point in the queue is reached
     * @return the objects the command returned when executed. you should probably return these to the player
     * unchanged if called from a peripheral method.
     * @see ITurtleCommand
     */
    public Object[] executeCommand( ILuaContext context, ITurtleCommand command ) throws LuaException, InterruptedException;

    /**
     * TODO: Document me
     */
    public void playAnimation( TurtleAnimation animation );

	/**
	 * Returns the turtle on the specified side of the turtle, if there is one.
	 * @return the turtle on the specified side of the turtle, if there is one.
	 */
	public ITurtleUpgrade getUpgrade( TurtleSide side );

    /**
     * TODO: Document me
     */
    public void setUpgrade( TurtleSide side, ITurtleUpgrade upgrade );

	/**
	 * Returns the peripheral created by the upgrade on the specified side of the turtle, if there is one.
	 * @return the peripheral created by the upgrade on the specified side of the turtle, if there is one.
	 */
	public IPeripheral getPeripheral( TurtleSide side );

    /**
     * TODO: Document me
     */
    public NBTTagCompound getUpgradeNBTData( TurtleSide side );

    /**
     * TODO: Document me
     */
    public void updateUpgradeNBTData( TurtleSide side );
}