algds.contest
Class Hamster

java.lang.Object
  |
  +--algds.contest.Hamster
public class Hamster
extends java.lang.Object
implements Constants

Basisklasse fuer alle Hamster, die sich im Labyrinth bewegen sollen. Jede Implementierung muss von dieser Klasse abgeleitet werden und die Methode run ueberschreiben. Eine Instanz der abgeleiteten Klasse wird in die Labyrinth-Welt geladen und dort gestartet.
Alle Konstanten-Werte und Methoden koennen ohne Ankuendigung bis zum 12.03.2001 geaendert werden, der grundlegende Aufbau wird sich aber nicht mehr aendern.

Aenderungen:
31.01.2001: Erste oeffentliche Version.
08.02.2001: Die Konstanten befinden sich nun im Interface algds.contest.Constants, welches von Hamster implementiert wird. Diese Konstanten koennen direkt als CORN angesprochen werden, man muss nicht Constants.CORN schreiben!
getCorn heisst jetzt getAvailableCorn.
05.03.2001: Der Hamster hat stets eine Zeitspanne von Constants.INFINITE_LOOP Millisekunden, um einen der Befehle forward(), beamMeUp() oder turn(int) aufzurufen. Nach einem solchen Aufruf hat er wieder soviel Zeit usw. Damit soll verhindert werden, dass ein Hamster ewig in einer Endlosschleife haengt, denn beim Aufruf einer der drei Methoden verliert er Energie, so dass er "nach endlicher Zeit" (das kann eine Weile dauern...) verhungert ist.
08.03.2001: Neue Hamster-Methoden verbose(), debuglog(String), debuglogln(String). Beim Aufruf von beamMeUp() wird dem Hamster stets Energie abgezogen, auch wenn nicht gebeamt werden kann.
30.04.2001: Nach einer bestimmten Gesamtlaufzeit (Constants.TOTAL_RUNTIME) wird der Lauf des Hamster abgebrochen. Auf diese Weise kann ein Hamster sich nicht 2 Wochen Zeit lassen :-)
04.05.2001: Korrektur der Gesamtzeitkontrolle.

Wer Fragen hat, stelle die bitte an Christian.

Version vom 04.05.2001

Author:
Kai-Uwe Sattler, Christian Semrau, Stephan Finn
See Also:
Constants

Constructor Summary
Hamster()
          Konstruktor zum Erzeugen eines Hamster-Objektes.
 
Method Summary
 boolean atHome()
          Gibt true zurueck, wenn der Hamster sich auf dem Heimatfeld befindet, false sonst.
 boolean beamMeUp()
          Beamt den Hamster auf ein anderes Feld.
 void debuglog(java.lang.String msg)
          Gibt die Statusmeldung nur dann aus, wenn der Hamster ausfuehrliche Meldungen geben soll.
 void debuglogln(java.lang.String msg)
          Gibt die Statusmeldung nur dann aus, wenn der Hamster ausfuehrliche Meldungen geben soll.
 int drop(int groesse, int anzahl)
          Legt die angegebene Anzahl von Koernern im aktuellen Feld ab.
 int eat(int groesse, int anzahl)
          Frisst die angegebene Anzahl von Koernern.
 boolean forward()
          Bewegt den Hamster um einen Schritt in der aktuellen Richtung vorwaerts.
 int[] getAvailableCorn()
          Liefert die Anzahl der verfuegbaren Koerner auf dem aktuellen Feld.
 int getAvailableCorn(int groesse)
          Liefert die Anzahl der verfuegbaren Koerner der gegebenen Groesse auf dem aktuellen Feld.
 int[] getCarriedCorn()
          Liefert die Anzahl der Koerner die der Hamster im Maul traegt.
 int getCarriedCorn(int groesse)
          Liefert die Anzahl der Koerner gegebener Groesse, die der Hamster im Maul traegt.
 int[] getCollectedCorn()
          Liefert die Anzahl der gesammelten Koerner auf dem Heimatfeld.
 int getCollectedCorn(int groesse)
          Liefert die Anzahl der gesammelten Koerner der gegebenen Groesse auf dem Heimatfeld.
 int getCollisions()
          Liefert die Anzahl der bisher gemachten Kollisionen.
 int getDirection()
          Liefert die aktuelle Laufrichtung des Hamsters als Himmelsrichtung.
 int getEnergy()
          Liefert die aktuelle Energie des Hamsters.
 int getHomeLevel()
          Liefert die Levelnummer des Heimatfeldes.
 int getHomeX()
          Liefert die X-Koordinate des Heimatfeldes.
 int getHomeY()
          Liefert die Y-Koordinate des Heimatfeldes.
 int getLevel()
          Liefert die Levelnummer der aktuellen Ebene des Labyrinthes.
 java.lang.String getName()
          Liefert den Namen des Hamsters.
 int getPoints()
          Liefert die aktuelle Punktzahl des Hamsters.
 int getSteps()
          Liefert die Anzahl der bisher ausgefuehrten Schritte.
 int getTurns()
          Liefert die Anzahl der bisher ausgefuehrten Drehungen.
 int getX()
          Liefert die aktuelle x-Position im Labyrinth.
 int getY()
          Liefert die aktuelle y-Position im Labyrinth.
 boolean isEngineAlive()
          Prueft, ob die Engine noch existiert
 void log(java.lang.String msg)
          Gibt eine Meldung in Form eines Strings im Log-Fenster aus.
 void logln(java.lang.String msg)
          Gibt eine Meldung in Form eines Strings im Log-Fenster aus.
 int look()
          Liefert Informationen ueber das in Blickrichtung angrenzende Feld.
 int lookCurrent()
          Liefert Informationen ueber das Feld, auf dem der Hamster gerade steht.
 void run()
          Die Hauptmethode des Hamsters.
 void setEngine(algds.contest.MazeEngine me)
          Interne Methode fuer die Ablaufumgebung.
 int take(int groesse, int anzahl)
          Nimmt die angegebene Anzahl von Koernern aus dem aktuellen Feld auf.
 void turn(int direction)
          Aendert die Laufrichtung, wobei das aktuelle Feld nicht verlassen wird.
 boolean verbose()
          Gibt an, ob der Hamster ausfuehrliche Statusmeldungen geben soll.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Hamster

public Hamster()
Konstruktor zum Erzeugen eines Hamster-Objektes. Sollte nichts tun! Alle Initialisierungen und Handlungen des Hamsters muessen in der Methode run() geschehen, denn die Hamsterbefehle funktionieren nicht, bevor run() aufgerufen wird.
Method Detail

isEngineAlive

public boolean isEngineAlive()
Prueft, ob die Engine noch existiert

setEngine

public void setEngine(algds.contest.MazeEngine me)
Interne Methode fuer die Ablaufumgebung. Darf vom Hamster nicht verwendet werden.

Setzt oder entfernt die Engine des Hamster.

Sie ist public, um Interessierten die Moeglichkeit zu geben, eigene MazeEngines zu schreiben und zu verwenden, so wie das letztes Jahr mit dem MazeRunnerX von Johannes Zander geschah, der nicht zum Originalpaket gehoerte. (Der sich aber als so gut erwiesen hat, dass dieses Jahr die ganze Umgebung auf seiner Engine aufbaut.)
Diese Methode wird waehrend des Wettbewerb nicht mehr public sein.

Parameters:
me - die Engine, oder null wenn sie entfernt werden soll.

take

public int take(int groesse,
                int anzahl)
Nimmt die angegebene Anzahl von Koernern aus dem aktuellen Feld auf. Wenn weniger daliegt, nimmt er nur was da ist. Wenn er weniger ins Maul kriegt, nimmt er nur, was reinpasst.
Parameters:
groesse - die Groesse der aufzunehmenden Koerner
anzahl - die Anzahl der aufzunehmenden Koerner
Returns:
int die Anzahl der tatsaechlich aufgenommenen Koerner
See Also:
Constants.CORNCARRY_MAX, Constants.CORNSIZE_MAX

drop

public int drop(int groesse,
                int anzahl)
Legt die angegebene Anzahl von Koernern im aktuellen Feld ab. Wenn er weniger hat, legt er nur ab, was er hat. Wenn nicht alles aufs Feld passt, wird nur abgelegt, was draufpasst (alle Felder ausser dem Heimatfeld haben nur Platz fuer ein Volumen von CORNFIELD_MAX Groesseneinheiten).
Parameters:
groesse - die Groesse der abzulegenden Koerner
anzahl - die Anzahl der abzulegenden Koerner
Returns:
int die Anzahl der tatsaechlich abgelegten Koerner
See Also:
Constants.CORNFIELD_MAX, Constants.CORNSIZE_MAX

eat

public int eat(int groesse,
               int anzahl)
Frisst die angegebene Anzahl von Koernern. Diese Koerner muss der Hamster schon im Maul tragen, wenn er weniger traegt, frisst er alles was er von der Groesse hat. Die Energie des Hamsters wird dadurch um den Wert n*groesse*ENERGY_CORN aufgeladen (wobei n das Minimum aus anzahl und der Kornzahl [der gegebenen Groesse] ist, die der Hamster tatsaechlich im Maul traegt), hoechstens jedoch auf den Wert ENERGY_MAX.
Parameters:
groesse - die Groesse der zu fressenden Koerner
anzahl - die Anzahl der zu fressenden Koerner
Returns:
int die Anzahl der tatsaechlich gefressenen Koerner
See Also:
Constants.ENERGY_CORN, Constants.ENERGY_MAX, Constants.CORNSIZE_MAX

beamMeUp

public boolean beamMeUp()
                 throws HamsterDiedException
Beamt den Hamster auf ein anderes Feld. Bringt den Hamster zum "anderen Ende" des Beamers. Das ist ein Feld, auf dem ein Beamer steht, der den Hamster wieder zurueckbringt. Wenn kein Beamer auf dem aktuellen Feld ist, wird auch nicht gebeamt, und false geliefert.
Die Energie aendert sich vor dem Beamen um ENERGY_STEP, egal ob dann gebeamt wird oder nicht.
Es koennen auch auf Beamerfeldern Maiskoerner liegen (look() und lookCurrent() liefern dann CORN | BEAMER zurueck).
Das Heimatfeld kann ebenfalls einen Beamer haben.
Returns:
true, wenn gebeamt werden konnte, sonst false (kein Beamer da).
Throws:
HamsterDiedException - wenn der Hamster verhungert ist.
See Also:
Constants.ENERGY_STEP

forward

public boolean forward()
                throws HamsterDiedException
Bewegt den Hamster um einen Schritt in der aktuellen Richtung vorwaerts. Seine Energie aendert sich nach dem Schritt um ENERGY_STEP Energiepunkte. Bei einer Kollision wird der Hamster einmal nach links gedreht. Seine Energie aendert sich nach der Kollision um ENERGY_TURN+ENERGY_COLLISION Energiepunkte.
Returns:
true, wenn Schritt ausgefuehrt werden konnte, sonst false (Kollision).
Throws:
HamsterDiedException - wenn der Hamster verhungert ist.
See Also:
Constants.ENERGY_STEP, Constants.ENERGY_COLLISION, Constants.ENERGY_TURN

turn

public void turn(int direction)
          throws HamsterDiedException
Aendert die Laufrichtung, wobei das aktuelle Feld nicht verlassen wird. Seine Energie aendert sich nach der Drehung um ENERGY_TURN.
Parameters:
direction - Drehrichtung (TURN_LEFT oder TURN_RIGHT)
Throws:
HamsterDiedException - wenn der Hamster verhungert ist.
See Also:
Constants.TURN_LEFT, Constants.TURN_RIGHT, Constants.ENERGY_TURN

look

public int look()
Liefert Informationen ueber das in Blickrichtung angrenzende Feld.
Returns:
Eine bitweise-oder-Kombination folgender Werte:
CORN fuer ein Feld mit Koernern
WALL, wenn das Feld in dieser Richtung durch eine Wand begrenzt ist
BEAMER wenn auf dem Feld ein Beamer ist
Liegt keiner der Faelle vor, wird EMPTY geliefert.
See Also:
Constants.EMPTY, Constants.CORN, Constants.WALL, Constants.BEAMER

lookCurrent

public int lookCurrent()
Liefert Informationen ueber das Feld, auf dem der Hamster gerade steht.
Returns:
Eine bitweise-oder-Kombination folgender Werte:
CORN fuer ein Feld mit Koernern
BEAMER wenn auf dem Feld ein Beamer ist
Liegt keiner der Faelle vor, wird EMPTY geliefert.
See Also:
Constants.EMPTY, Constants.CORN, Constants.BEAMER

getDirection

public int getDirection()
Liefert die aktuelle Laufrichtung des Hamsters als Himmelsrichtung.
Returns:
Laufrichtung (DIR_WEST, DIR_NORTH, DIR_EAST, DIR_SOUTH)
See Also:
Constants.DIR_WEST, Constants.DIR_NORTH, Constants.DIR_EAST, Constants.DIR_SOUTH

getSteps

public int getSteps()
Liefert die Anzahl der bisher ausgefuehrten Schritte.
Returns:
Anzahl der Schritte

getCollisions

public int getCollisions()
Liefert die Anzahl der bisher gemachten Kollisionen.
Returns:
Anzahl der Kollisionen

getEnergy

public int getEnergy()
Liefert die aktuelle Energie des Hamsters. Ein Wert <= 0 bedeutet, dass der Hamster verhungert ist.
Returns:
Energievorrat des Hamsters

atHome

public boolean atHome()
Gibt true zurueck, wenn der Hamster sich auf dem Heimatfeld befindet, false sonst.
Returns:
Hamster zuhause true/false
See Also:
getLevel(), getX(), getY(), getHomeLevel(), getHomeX(), getHomeY()

getHomeLevel

public int getHomeLevel()
Liefert die Levelnummer des Heimatfeldes. Die Ebenen sind aufsteigend nummeriert, die unterste Ebene hat dabei die Nummer 0.
Returns:
Levelnummer des Heimatfeldes

getHomeX

public int getHomeX()
Liefert die X-Koordinate des Heimatfeldes. Koordinaten koennen positiv oder negativ sein!
Returns:
X-Koordinate des Heimatfeldes

getHomeY

public int getHomeY()
Liefert die Y-Koordinate des Heimatfeldes. Koordinaten koennen positiv oder negativ sein!
Returns:
Y-Koordinate des Heimatfeldes

getLevel

public int getLevel()
Liefert die Levelnummer der aktuellen Ebene des Labyrinthes. Die Ebenen sind aufsteigend nummeriert, die unterste Ebene hat dabei die Nummer 0.
Returns:
Nummer der aktuellen Ebene

getX

public int getX()
Liefert die aktuelle x-Position im Labyrinth. Koordinaten koennen positiv oder negativ sein!
Returns:
x-Position

getY

public int getY()
Liefert die aktuelle y-Position im Labyrinth. Koordinaten koennen positiv oder negativ sein!
Returns:
y-Position

getCarriedCorn

public int[] getCarriedCorn()
Liefert die Anzahl der Koerner die der Hamster im Maul traegt.
Liefert ein int-Feld der Laenge 1+CORNSIZE_MAX mit folgenden Elementen:
[0] = Gesamtgroesse aller Maiskoerner
[1] = Anzahl der Koerner der Groesse 1
[2] = Anzahl der Koerner der Groesse 2
...
[CORNSIZE_MAX] = Anzahl der Koerner der Groesse CORNSIZE_MAX
Returns:
int[] Anzahl der Koerner
See Also:
Constants.CORNSIZE_MAX

getCarriedCorn

public int getCarriedCorn(int groesse)
Liefert die Anzahl der Koerner gegebener Groesse, die der Hamster im Maul traegt.
Parameter groesse -- Ergebnis:
0: Gesamtgroesse aller Maiskoerner
1: Anzahl der Koerner der Groesse 1
2: Anzahl der Koerner der Groesse 2
...
CORNSIZE_MAX: Anzahl der Koerner der Groesse CORNSIZE_MAX
Parameters:
groesse - Groesse der Koerner, deren Anzahl geliefert werden soll.
Returns:
int Anzahl der Koerner
See Also:
Constants.CORNSIZE_MAX

getCollectedCorn

public int[] getCollectedCorn()
Liefert die Anzahl der gesammelten Koerner auf dem Heimatfeld.
Liefert ein int-Feld der Laenge 1+CORNSIZE_MAX mit folgenden Elementen:
[0] = Gesamtgroesse aller Maiskoerner
[1] = Anzahl der Koerner der Groesse 1
[2] = Anzahl der Koerner der Groesse 2
...
[CORNSIZE_MAX] = Anzahl der Koerner der Groesse CORNSIZE_MAX
Returns:
int[] Anzahl der Koerner
See Also:
Constants.CORNSIZE_MAX

getCollectedCorn

public int getCollectedCorn(int groesse)
Liefert die Anzahl der gesammelten Koerner der gegebenen Groesse auf dem Heimatfeld.
Parameter groesse -- Ergebnis:
0: Gesamtgroesse aller Maiskoerner
1: Anzahl der Koerner der Groesse 1
2: Anzahl der Koerner der Groesse 2
...
CORNSIZE_MAX: Anzahl der Koerner der Groesse CORNSIZE_MAX
Parameters:
groesse - Groesse der Koerner, deren Anzahl geliefert werden soll.
Returns:
int Anzahl der Koerner
See Also:
Constants.CORNSIZE_MAX

getAvailableCorn

public int[] getAvailableCorn()
Liefert die Anzahl der verfuegbaren Koerner auf dem aktuellen Feld.
Liefert ein int-Feld der Laenge 1+CORNSIZE_MAX mit folgenden Elementen:
[0] = Gesamtgroesse aller Maiskoerner
[1] = Anzahl der Koerner der Groesse 1
[2] = Anzahl der Koerner der Groesse 2
...
[CORNSIZE_MAX] = Anzahl der Koerner der Groesse CORNSIZE_MAX
Returns:
int[] Anzahl der Koerner
See Also:
Constants.CORNSIZE_MAX

getAvailableCorn

public int getAvailableCorn(int groesse)
Liefert die Anzahl der verfuegbaren Koerner der gegebenen Groesse auf dem aktuellen Feld.
Parameter groesse -- Ergebnis:
0: Gesamtgroesse aller Maiskoerner
1: Anzahl der Koerner der Groesse 1
2: Anzahl der Koerner der Groesse 2
...
CORNSIZE_MAX: Anzahl der Koerner der Groesse CORNSIZE_MAX
Parameters:
groesse - Groesse der Koerner, deren Anzahl geliefert werden soll.
Returns:
int Anzahl der Koerner
See Also:
Constants.CORNSIZE_MAX

getPoints

public int getPoints()
Liefert die aktuelle Punktzahl des Hamsters.
Punkte =
POINTS_CORN * getCollectedCorn(0)
+POINTS_STEP * getSteps()
+POINTS_COLLISION * getCollisions()
zusätzlich kommen nach Ende des Laufs hinzu (das wird der Hamster selbst dann nicht mehr abrufen koennen):
Wenn Absturz oder Zeitüberschreitung: POINTS_CRASH
sonst Wenn verhungert: POINTS_DIE
sonst Wenn nicht auf Heimatfeld beendet: POINTS_NOTHOME
sonst 0
Returns:
int

log

public void log(java.lang.String msg)
Gibt eine Meldung in Form eines Strings im Log-Fenster aus. Ob tatsaechlich eine Ausgabe erfolgen soll, kann in der "World" mit dem Menu-Eintrag Hamster/Mute eingestellt werden.
Parameters:
msg - die auszugegebende Nachricht

logln

public void logln(java.lang.String msg)
Gibt eine Meldung in Form eines Strings im Log-Fenster aus.
Fuehrt die folgende Anweisung aus:
log(msg+"\n");
Parameters:
msg - die auszugegebende Nachricht
See Also:
log(java.lang.String)

verbose

public boolean verbose()
Gibt an, ob der Hamster ausfuehrliche Statusmeldungen geben soll. Der Wert dieser Funktion kann in der "World" mit dem Menu-Eintrag Hamster/Verbose eingestellt werden.
Returns:
Ausfuehrliche Meldungen geben
See Also:
debuglog(java.lang.String)

debuglog

public void debuglog(java.lang.String msg)
Gibt die Statusmeldung nur dann aus, wenn der Hamster ausfuehrliche Meldungen geben soll.
Fuehrt die folgende Anweisung aus:
if (verbose()) log(msg);
Parameters:
msg - die auszugebende Meldung
See Also:
verbose(), log(java.lang.String)

debuglogln

public void debuglogln(java.lang.String msg)
Gibt die Statusmeldung nur dann aus, wenn der Hamster ausfuehrliche Meldungen geben soll.
Fuehrt die folgende Anweisung aus:
debuglog(msg+"\n");
Parameters:
msg - die auszugebende Meldung
See Also:
debuglog(java.lang.String)

getName

public java.lang.String getName()
Liefert den Namen des Hamsters. Kann ueberschrieben werden, um einen anderen Namen als den Klassennamen zu liefern.

run

public void run()
Die Hauptmethode des Hamsters. Durch Ueberschreiben dieser Methode erfolgt die Bewegung durch das Labyrinth.

Verhungert der Hamster, dann wird von forward(), beamMeUp() oder turn(int) eine HamsterDiedException geworfen.
Soll der Hamster vom Benutzer gestoppt werden, dann wird eine HamsterStopException geworfen, die den Hamster beim naechsten Aufruf einer der Hamster-Methoden beendet.

getTurns

public int getTurns()
Liefert die Anzahl der bisher ausgefuehrten Drehungen.
Returns:
Anzahl der Drehungen