Minecraft API (Pi Edition)

Minecraften arrakastaren funtsa, hein batean, ematen dituen mugagabeko sormen-aukeretan dago. Izan ere, sandbox edo hondarrezko jolas-kutxa birtuala bailitzan, kuboz eraikitako mundu batean sinpleki jolastu eta eraikitzea du giltzarria. Sinpletasun horren baitan, baliabide gutxi behar ditu teknikoki martxan ibiltzeko, eta, abantaila horri esker, hain zuzen, edozein gailutara moldatzen da: ordenagailuetara, telefonoetara, tabletetara, mahai gaineko bideo-jokoen sistemetara... Ingurune bakoitzak programazio-lengoaia desberdinak behar dituenez, Minecraft hainbat lengoaiatan idatzirik dago.

MCPI liburutegiaren egitura

Honela egituratzen da MCPI izeneko APIa (.py amaiera dutenak Python formatuko fitxategiak dira eta horien barnean desglosatutakoak, aldiz, bakoitzak gordetzen dituen objektuak):

• minecraft.py
  • Class Minecraft klasea: klase nagusia, jokora konektatu eta eragiteko
    • Class camera azpiklasea: kameraren angelua eta kokapena kontrolatzeko
    • Class player azpiklasea: erabiltzailearen posizioa edo kokapena jaso eta aldatzeko
    • Class entity azpiklasea: entitateen xehetasunak eguneratzeko zein kokapena jaso eta aldatzeko (eraikinak, konektatutako jokalariak, objektuak, eta abar)
    • Class events azpiklasea: jokoko gertaeren kontrola
• block.py
  • Class Block klasea: blokeen eta bloke moten definizioa
• event.py
  • Class BlockEvent klasea: bloke bakoitzaren gertaeren xehetasunak jasotzeko, batik bat zer, zeini eta zeinen (erabiltzailea) eraginez gertatzen diren
• vec3.py
  • Class Vec3 klasea: Pythonen klase generikoa, 3 dimentsioko bektoreak kudeatzeko (i.e. x, y, z)
• connection.py: APIaren barne-zereginetarako modulua
• util.py: APIaren barne-zereginetarako modulua

Honako hauek dira erabilgarri dauden fitxategien barneko atributuen eta funtzioen azalpenak eta erabilera-esparruak:

Minecraft klasea

Minecraft munduari eragiteko behar-beharrezko klasea da. Kasu honetan, martxan dagoen Minecraft instantzia batera konektatzeko prestatuta dagoen objektu berezi bat da (mcpi.minecraft), hau da, abiarazita dagoen partidara batzeko eta hari eragiteko instantzia: funtzioak ditu partidara konektatzeko, jokalariak eta blokeak eguneratzeko eta gertaerak jasotzeko. Kakotx artean funtzio bakoitza zer den eta nola erabili azaltzen da, eta kodean bertan gorriz nabarmendutako iruzkinak argibide gehiago emateko jarri dira.

.create(address = "localhost", port = 4711)

"Minecraft partida batera konexioa ezartzeko (sareko helbidea, portua) => Minecraft objektua (partida)"

#lehentasunezko helbidearekin eta portuarekin hasi partida

mc = minecraft.Minecraft.create()

#ezarri helbidea eta portua eta batu partidara

mc = minecraft.Minecraft.create("192.168.0.12", 4711)

.getBlock(x, y, z)

"Jaso bloke mota (x, y, z) => id:int"

#eskuratu 0,0,0 koordenatuko bloke mota

blockType = mc.getBlock(0,0,0)

.getBlockWithData(x, y, z)

"Jaso bloke osoa (x, y, z) => Blokea"

#eskuratu 0,0,0 koordenatuko blokea

blockObj = mc.getBlockWithData(0,0,0)

.setBlock(x, y, z)

"Ezarri blokea (x, y, z, id,[egoera])"

#ezarri x, y, z koordenatuan blokea, mota eta egoera zehaztuz

mc.setBlock(0,0,0,block.DIRT.id)

#ezarri x, y, z koordenatuan blokea, mota eta azpimota (egoera) zehaztuz

mc.setblock(0,0,0,block.WOOD.id, 1)

.setBlocks(x0,y0,z0,x1,y1,z1,blockType, blockData)

"Osatu blokezko kuboidea (x0, y0, z0, x1, y1, z1, id, [egoera])"

#ezarri hainbat bloke aldi berean, adierazitako koordenatu paretik besteraino

mc.setBlocks(-1, -1, -1, 1, 1, 1, block.STONE.id)

.getHeight(x, z)

"Itzuli munduaren altuera (x, z) => int"

#x eta y koordenatuei dagokien y balio altuena jaso (airea ez den azkenarena, alegia) 

y = mc.getHeight(0,0)

.getPlayerEntityIds()

"Eskuratu konektatuta dauden jokalarien entitate ID zenbakiak => [id:int]"

#idatzi partidara konektatu diren jokalarien entitate id zenbakia

entityIds = mc.getPlayerEntityIds()

for entityId in entityIds:

   print entityId

.saveCheckpoint()

"Gorde partida, etorkizunean mundua utzi bezala berreskuratzeko”

mc.saveCheckpoint()

.restoreCheckpoint()

"Itzuli gordetako partidara"

mc.restoreCheckpoint()

.postToChat(message)

"Erantsi mezu bat jokoaren txatean"

#esan 'Kaixo, Minecraft mundua!’ partidako txat-leihoan 

mc.postToChat("Kaixo, Minecraft mundua!")

.setting(setting, status)

"Jarri mundu baten ezarpenak (gakoa, balioa). Gako-aukera: world_immutable, nametags_visible"

#mundua aldaezin bihurtzeko ezarpena aktibatu

mc.setting("world_immutable", True)

#jokalarien izenak bistaratzeko ezarpena desaktibatu

mc.setting("nametags_visible", False)

Jokalariaren azpiklasea (Minecraft.player)

.getPos()

"Jaso zenbaki errealetan (hamartar batekin) erabiltzailearen kokapenaren koordenatuak. Bloke baten erdian dagoenean, x.5 itzultzen du"

#eskuratu erabiltzailearen posizioa zenbaki errealetan

playerPos = mc.player.getPos()

.setPos(x,y,z)

"Mugitu erabiltzailea adierazitako koordenatura ([x, y, z])"

#ezarri erabiltzailearen kokapena zenbaki erreal bidez

mc.player.setPos(0.0,0.0,0.0)

.getTilePos()

"Itzuli jokalaria dagoen uneko tile-a edo ingurune-zatiaren balioa"

#eskuratu jokalaria dagoen uneko tile edo ingurune-zatiaren balioa

playerTile = mc.player.getTilePos()

.setTilePos(x,y,z)

"Bidali jokalaria munduko tile ingurune batera koordenatu bidez ([x, y, z])"

#ezarri jokalaria dagoen tile ingurunearentzat balioa

mc.player.setTilePos(0,0,0)

.setting(setting, status)

"Ezarri jokalariaren ezarpenak (gakoa, balioa). Gako-aukerak: autojump"

#automatikoki jauzi egiteko aukera aktibatu 

mc.player.setting("autojump", True)

Entitateen azpiklasea (Minecraft.entity)

Entitateei dagozkien funtzioak erabiltzen dira jokoko-entitateei eragiteko (haien artean, jokalariei). Konektaturiko jokalariak bereizteko identifikazioak eskuratzeko erabiltzen da .getPlayerEntityIds() funtzioa. Entitateen funtzioak oso erabilgarriak dira multiplayer edo sare bidezko partidak kudeatzeko.

#partidara konektaturiko jokalarien id balioak lortu

entityIds = mc.getPlayerEntityIds()

1stEntityId = entityIds[0]

2ndEntityId = entityIds[1]

...

.getPos(entityId)

"Jaso zenbaki errealetan (hamartar batekin) entitatearen kokapenaren koordenatuak. Bloke baten erdian dagoenean, x.5 itzultzen du"

#eskuratu entitatearen posizioa zenbaki errealetan

entityPos = mc.entity.getPos(entityId)

.setPos(entityId,x,y,z)

"Mugitu entitatea adierazitako koordenatura (id, [x ,y, z])"

#ezarri entitatearen kokapena zenbaki errealen bidez

mc.player.setPos(entityId,0.0,0.0,0.0)

.getTilePos(entityId)

"Itzuli entitatea dagoen uneko tile-a edo ingurune-zatiaren balioa"

#eskuratu entitatea dagoen uneko tile edo ingurune-zatiaren balioa

entityTile = mc.entity.getTilePos(entityId)

.setTilePos(entityId, x,y,z)

"Bidali entitatea munduko tile ingurune batera koordenatu bidez ([x, y, z])"

#ezarri entitatea dagoen tile ingurunearentzat balioa

mc.player.setTilePos(entityId,0,0,0)

Ikuspegien azpiklasea (Minecraft.camera)

.setNormal(entityId)

"Ezarri jokalari baten kamera Minecraften lehentasunezko ikusmoldean ([entityId])"

#berrezarri jokalari zehatz baten ikusmoldea lehentasunezkoan 

mc.camera.setNormal(entityId)

.setFixed()

"Utzi kamera finkatuta”

#ikusmolde finkoa ezarri 

mc.camera.setFixed()

.setFollow(entityId)

"Ezarri kamera entitate bati jarraitzeko eran ([entityId])"

#doitu kamera jokalari zehatz bati jarraitzeko 

mc.camera.setFollow(entityId)

.setPos(x,y,z)

"Finkatu kamera kokapen zehatz batean (x,y,z)"

#x, y, z lekuan jarri kamera finkatuta

mc.camera.setPos(0,0,0)

Gertaeren azpiklasea (Minecraft.events)

.pollBlockHits()

"Eskuratu blokeei emandako ezpata-kolpeak => [BlockEvent]"

#bildu ezpata-kolpeak azkeneko aldiz deitu zitzaionetik

blockEvents = mc.events.pollBlockHits()

for blockEvent in blockEvents:

    print blockEvent

.clearAll()

"Hustu gertaera-zerrenda"

#ezabatu jaso zirenetik orain arteko gertaera guztiak 

mc.events.clearAll()

Block klasea

Minecrafteko blokeak definitzeko egitura edo gordailua da Block: zein motatakoak diren eta zein egoeratan dauden zehazten du. Konstanteak ere definitzen dira, erosoago erabiltzeko eta uneoro identitate-zenbakiekin gogoratu beharrik ez izateko. Adibidez, BLOCK.AIR.id aldagaiak barruan 0 balioa du eta gizakiontzako errazagoa da gogoratzeko bakoitzari dagokion zenbakia baino. Minecraft Pi bertsioan eskuragarri dauden id eta data guztien zerrenda dago Bloke ID zerrenda azpiatalean.

#sortu mota zehatz bateko blokea 

blokeObj1 = block.Block(id)

#sortu mota zehatz bateko blokea eta egokitu egoera bat 

blokeObj2 = block.Block(id, egoera)

#artile arrosa

artileBlokea1=block.Block(35,6)

.id

"Bloke baten id (mota)"

#aurreko adibidekoaren baliokidea da honako hau (artile arrosa)

artileBlokea2=block.Block(BLOCK.WOOL.id,6)

.data

"Bloke baten egoera (azpimota)"

#dinamita eztanda egiteko egoeran

dinamitaBlokea=block.Block(BLOCK.TNT.id, 1)

#kolorea ere, egoera adierazteko azpimota da (arrosa)

artileBlokea2=block.Block(BLOCK.WOOL.id,6) 

Blokeen inguruko gertaeren klasea (Minecraft.BlockEvent)

"Blokeei eragiten dieten gertaeren berri jasotzen da BlokeEvent egituretan. Minecraft.events.pollBlockHits() funtzioak biltzen ditu eta aldagai batean jasotzen dira.”

blockEvent = mc.events.pollBlockHits()

.type

"Gertaera mota adierazten du, baina gaur-gaurkoz bakarra dago inplementaturik: BlockEvent.HIT"

blockEventType = blockEvent.type

Gertaera motak:

0: BlockEvent.HIT

.pos

"Gertaera jasotako blokearen kokapena; esaterako, ezpataz jotako blokea. .pos funtzioak itzultzen du Vec3 erako objektua, x, y, z koordenatuak gordetzen dituena"

blokeGertaerarenPos = BlockEvent.pos

.face

"Jaso gertaera blokearen zein aldetan izan den"

blokeGertaerarenAldea = BlockEvent.face

.entityId

"Jaso gertaeraren erantzulearen entityId edo entitatearen zenbakizko balio bereizgarria (identitatea); esaterako, blokea jo duen jokalariarena"

blokeGertaerarenErantzulea = BlockEvent.entityId

Espazioa kudeatzeko klasea (Vec3)

“3 dimentsioko bektore bat definitzeko egitura da. Minecraften, x, y, eta z multzoaren balioak, koordenatuak, alegia, zehazteko balio du: x eta z posizio horizontala zehazteko eta y posizio bertikala irudikatzeko"

#gorde lehentasunezko berpizte-lekuaren balioa 

kokapena = vec3.Vec(0,0,0)