Discussion on API

From 8x9craft
Jump to: navigation, search

Crab

Movement

Movement in six directions + turning, teleporting.

// Movement
forward(): boolean
back(): boolean
up(): boolean
down(): boolean
turnLeft(): boolean
turnRight(): boolean
stepLeft(): boolean
stepRight(): boolean

// Teleportation
home(name: string): boolean

Discussion

  • Should we be able to set home as well?
    crab.setHome('name')
    
    • It could only work inside current execution context, a temporary home:
      // Dig a cross from current location
      crab.setHome()
      for (let i = 0; i < 4; ++i) {
      	for (let j = 0; j < 4; ++j) {
      		crab.dig();
      		crab.forward();
      	}
      	crab.turnRight();
      	crab.home();
      }
      
    • But maybe let also specify many homes during execution:
      // Deepen the corridor
      var facing = crab.getFacing();
      var start = crab.setHome();				// or just: crab.setHome(0) / crab.setHome('start');
      while (!crab.isBlocked()) {
      	crab.forward();
      }
      var corridorStart = crab.setHome();
      
      crab.home(start);						// or just: start.go()
      crab.turnRight();
      crab.turnRight();
      while (!crab.isBlocked()) {
      	crab.forward();
      }
      var corridorEnd = crab.setHome();
      
      // Now we could do something like:
      crab.home(corridorEnd);
      crab.face(facing);
      crab.say('Ready to build corridor of length: ' + (corridorEnd.pos - corridorStart.pos).len());
      while (!crab.pos() == corridorEnd) {
      	crab.digDown();
      	crab.forward();
      }
      
      // Note that we could do the same by adding some methods to the Vector3i class.
      

World interaction

// Interacting with blocks and entities
dig(): boolean						// + up and down variations
attack(): boolean					// + up and down variations

// Learning of world's state
isBlocked(): boolean				// + up and down variations
inspect(): EntityInfo				// + up, down, left, right and back variations

// Redstone interaction
setRedStoneOutput(side: String, level: Number): boolean
getRedStoneInput(side: String): Number

Inventory / Items

// World-Inventory interaction
place(slotNo: number): boolean		// + up and down variations
pickItems(): boolean
use(slotNo: number): boolean		// + up and down variations
useLeft(): boolean					// + up and down variations
useRight(): boolean					// + up and down variations
throwItems(slotNo: Number): boolean
throwLeft(): boolean
throwRight(): boolean

// Manipulating inventory
grab(slotNo: Number): boolean
grabLeft(slotNo: Number): boolean
grabRight(slotNo: Number): boolean
swap(slotNoOne: Number, slotNoTwo: Number): boolean
getItemCount(slotNo: Number): boolean

// Crafting
craft(itemId: Number): Number
craft(itemName: String): Number
craft(itemId: Number, meta: Number): Number
craft(itemName: String, meta: Number): Number

Hakkun

// Player interaction
say(message: String): boolean

// Self inspection
getName(): String
getPosition(): Vector3i
getFacing(): Facing

Events / Execution

// Controling execution
sleep(tick: number): boolean

// Handling events
handleEvents(): void
onChatMessage(func: Function): void
onNeighborChangedEvent(func: Function): void

Discussion

  • should we rename handleEvents() to doEvents() or something similarly simple?
  • should we rename onChatMessage() to just onChat() (leaving onMessage() for future messaging between Hakkuns)?
  • should we rename onNeighborChangedEvent() to something along the lines of onNearbyBlockChanged()?

Owner

getPosition(): Vector3i
getFacing(): Facing
getDistance(): Number

Discussion

  • Maybe we should add a getName() so Hakkun can target player directly when saying something?

Vector3i

x: Number
y: Number
z: Number

Discussion

  • Can't we just name this class Position? JavaScript doesn't discern between integer and floating point types, so we wouldn't need another class for Entity's position either way.
  • I think we should add methods that will enable easy calculations with positions like var vec = pos1 - pos2; vec.len().

Facing

index: Number
opposite: Number
horizontalIndex: Number
name: String
directionVec: Vector3i

Discussion

  • Is it necessary to have so many fields in this class? Can't it hold only the name of its direction?

EntityInfo

name: String	
metadata: Number
isLiquid: boolean
isAir: boolean
properties: Object

Discussion

  • should we name the class BlockInfo instead?
  • should we create another class named EntityInfo that will hold information specific to entities (life, isAnimal, etc.)?
  • should we return only one or other from methods like inspect()?
  • what should we do if there is more than one entity within block bounds?