Skip to content

Commit

Permalink
Beefier javadocs
Browse files Browse the repository at this point in the history
  • Loading branch information
j-mao committed Jan 2, 2022
1 parent ddb0587 commit 3c8b672
Show file tree
Hide file tree
Showing 11 changed files with 265 additions and 94 deletions.
56 changes: 43 additions & 13 deletions engine/src/main/battlecode/common/AnomalyScheduleEntry.java
Original file line number Diff line number Diff line change
@@ -1,37 +1,67 @@
package battlecode.common;

/**
* AnomalyScheduleEntry describes a single anomaly in the schedule.
*
* You can access information about that anomaly's round number and type.
* AnomalyScheduleEntry describes a single Anomaly in the Anomaly schedule. The
* schedule of Anomalies is predetermined for each map, and you can retrieve it
* by calling {@link RobotController#getAnomalySchedule}. Each schedule entry
* provides information about the round on which it occurs, and the type of the
* Anomaly.
* <P>
* Note that the Singularity is not included in the schedule. You should instead
* check {@link GameConstants#GAME_MAX_NUMBER_OF_ROUNDS}.
*/
public class AnomalyScheduleEntry {

/**
* The round on which this Anomaly will occur. The Anomaly will occur at the
* end of this round, that is, after all robots have taken their turn.
*/
public final int roundNumber;

/**
* The type of this Anomaly.
*/
public final AnomalyType anomalyType;

public AnomalyScheduleEntry(int round, AnomalyType anomaly) {
/**
* Constructs an AnomalyScheduleEntry using the given round number and
* Anomaly type. Note that this does not actually insert the Anomaly into
* the schedule, but only creates a local object that you are free to
* manipulate. The global Anomaly schedule is fixed and cannot be changed;
* to envision an Anomaly with a Sage, see {@link RobotController#envision}.
*
* @param round the round number of the Anomaly
* @param type the type of the Anomaly
*/
public AnomalyScheduleEntry(int round, AnomalyType type) {
this.roundNumber = round;
this.anomalyType = anomaly;
this.anomalyType = type;
}

/**
* @return a copy of the entry
* Constructs a copy of this schedule entry. Note that this does not
* actually cause the Anomaly to happen twice, but only creates a local
* object that you are free to manipulate. The global Anomaly schedule is
* fixed and cannot be changed; to envision an Anomaly with a Sage, see
* {@link RobotController#envision}.
*
* @return a copy of this AnomalyScheduleEntry
*/
public AnomalyScheduleEntry copyEntry() {
return new AnomalyScheduleEntry(this.roundNumber, this.anomalyType);
}

/**
* Returns whether two AnomalyScheduleEntrys are equal.
* Returns whether two AnomalyScheduleEntry objects are equivalent.
*
* @param other the other anomaly schedule entry to compare to
* @return whether the two anomaly schedules entry are equivalent
* @param other the AnomalyScheduleEntry to compare with
* @return whether the two AnomalyScheduleEntry objects are equivalent
*
* @battlecode.doc.costlymethod
*/
public boolean equals(AnomalyScheduleEntry other) {
if (this.roundNumber != other.roundNumber) return false;
return this.anomalyType == other.anomalyType;
@Override
public boolean equals(Object other) {
if (other == null || getClass() != other.getClass()) return false;
AnomalyScheduleEntry casted = (AnomalyScheduleEntry) other;
return this.roundNumber == casted.roundNumber && this.anomalyType == casted.anomalyType;
}
}
62 changes: 59 additions & 3 deletions engine/src/main/battlecode/common/AnomalyType.java
Original file line number Diff line number Diff line change
@@ -1,20 +1,76 @@
package battlecode.common;

/**
* AnomalyType enumerates the different types of anomalies in the game.
* You can also access properties about these anomalies, such as their strengths
* and whether they can be performed by Sages.
* AnomalyType represents the type of a scheduled or envisioned Anomaly. You
* can access the type of scheduled Anomalies from
* {@link AnomalyScheduleEntry#anomalyType}, and envision your own Anomalies with
* Sages by using {@link RobotController#envision}.
* <P>
* AnomalyType also provides information about the strenghts of each Anomaly, as
* well as other properties.
* <P>
* Note that the Singularity is not included in the schedule. You should instead
* check {@link GameConstants#GAME_MAX_NUMBER_OF_ROUNDS}.
*/
public enum AnomalyType {
/**
* Abyss causes proportional amounts of metal resources to be lost. When
* global, the entire map as well as team reserves are affected. When
* envisioned, a local region of the map is affected.
* <P>
* {@link #globalPercentage} and {@link #sagePercentage} specify the
* proportion of metals lost.
*/
ABYSS (true, true, 0.1f, 0.2f),

/**
* Charge deals concentrated damage to Droids. When global, the top
* {@link #globalPercentage} Droids with the most nearby friendly units are
* destroyed. When envisioned, all nearby enemy Droids lose
* {@link #sagePercentage} of their maximum health.
*/
CHARGE (true, true, 0.05f, 0.1f),

/**
* Fury deals concentrated proportional damage to Turrets. When global, all
* Turrets are affected. When envisioned, a local region is affected.
* <P>
* {@link #globalPercentage} and {@link #sagePercentage} specify the
* amount of damage dealt, as a proportion of the Turret's maximum health.
*/
FURY (true, true, 0.05f, 0.1f),

/**
* Vortex upends the world by transforming the map terrain. It can only
* occur globally.
* <P>
* The values of {@link #globalPercentage} and {@link #sagePercentage} are
* unused.
*/
VORTEX (true, false, 0, 0),

SINGULARITY (true, false, 0, 0);

/**
* Whether this type of Anomaly could appear in the global schedule.
*/
public final boolean isGlobalAnomaly;

/**
* Whether this type of Anomaly could be envisioned by Sages.
*/
public final boolean isSageAnomaly;

/**
* The strength of this Anomaly when globally scheduled. The precise
* definition of this value depends on the Anomaly type.
*/
public final float globalPercentage;

/**
* The strength of this Anomaly when envisioned by a Sage. The precise
* definition of this value depends on the Anomaly type.
*/
public final float sagePercentage;

AnomalyType(boolean isGlobalAnomaly, boolean isSageAnomaly, float globalPercentage, float sagePercentage) {
Expand Down
17 changes: 8 additions & 9 deletions engine/src/main/battlecode/common/Clock.java
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,14 @@
import battlecode.instrumenter.inject.RobotMonitor;

/**
* Clock is a singleton that allows contestants to introspect the state of their running
* code.
* Clock is a singleton that allows contestants to introspect the state of their
* running code.
*
* @author james
*/
@SuppressWarnings("unused")
public final class Clock {

/**
/*
* IMPORTANT NOTE!
* This class is reloaded for every individual robot.
* See Loader for more information.
Expand All @@ -28,20 +27,20 @@ public static void yield() {

/**
* Returns the number of bytecodes this robot has left in this round.
* @return the number of bytecodes this robot has left in this round.
*
* @return the number of bytecodes this robot has left in this round
* @battlecode.doc.costlymethod
*/
public static int getBytecodesLeft() {
return RobotMonitor.getBytecodesLeft();
}

/**
* Returns the number of bytecodes the current robot has executed since the beginning
* of the current round.
* @return the number of bytecodes the current robot has executed since the beginning
* of the current round.
* Returns the number of bytecodes the current robot has executed since the
* beginning of the current round.
*
* @return the number of bytecodes the current robot has executed since the
* beginning of the current round
* @battlecode.doc.costlymethod
*/
public static int getBytecodeNum() {
Expand Down
21 changes: 13 additions & 8 deletions engine/src/main/battlecode/common/Direction.java
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,14 @@ public enum Direction {
CENTER(0, 0);

/**
* Change in x, change in y.
* Change in x.
*/
public final int dx, dy;
public final int dx;

/**
* Change in y.
*/
public final int dy;

Direction(int dx, int dy) {
this.dx = dx;
Expand Down Expand Up @@ -102,9 +107,9 @@ public Direction rotateRight() {

/**
* Returns a list of all directions. This is equivalent to calling
* Direction.values().
* {@link Direction#values}.
*
* @return array of all directions.
* @return array of all directions
*/
public static Direction[] allDirections() {
return Direction.values();
Expand All @@ -113,7 +118,7 @@ public static Direction[] allDirections() {
/**
* Returns a list of all cardinal directions.
*
* @return array of all cardinal directions.
* @return array of all cardinal directions
*/
public static Direction[] cardinalDirections() {
return new Direction[]{Direction.NORTH, Direction.EAST, Direction.SOUTH, Direction.WEST};
Expand All @@ -122,7 +127,7 @@ public static Direction[] cardinalDirections() {
/**
* Returns the delta X of the direction.
*
* @return the delta X of the direction.
* @return the delta X of the direction
*/
public int getDeltaX() {
return this.dx;
Expand All @@ -131,9 +136,9 @@ public int getDeltaX() {
/**
* Returns the delta Y of the direction.
*
* @return the delta Y of the direction.
* @return the delta Y of the direction
*/
public int getDeltaY() {
return this.dy;
}
}
}
2 changes: 1 addition & 1 deletion engine/src/main/battlecode/common/GameActionException.java
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ public GameActionException(GameActionExceptionType type, String message) {
* Gives the type of gameworld interaction that caused this GameActionException, which
* was specified when this instance was constructed.
*
* @return this GameActionException's type.
* @return this GameActionException's type
*/
public GameActionExceptionType getType() {
return type;
Expand Down
4 changes: 2 additions & 2 deletions engine/src/main/battlecode/common/GameConstants.java
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
package battlecode.common;

/**
* Defines constants that affect gameplay.
* GameConstants defines constants that affect gameplay.
*/
@SuppressWarnings("unused")
public class GameConstants {

/**
* The current spec version the server compiles with.
*/
public static final String SPEC_VERSION = "1.0";
public static final String SPEC_VERSION = "2022.0.1.0";

// *********************************
// ****** MAP CONSTANTS ************
Expand Down
2 changes: 1 addition & 1 deletion engine/src/main/battlecode/common/MapLocation.java
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ public final boolean isAdjacentTo(MapLocation location) {
* If <code>location</code> equals this location then the return value is Direction.CENTER.
*
* @param location The location to which the Direction will be calculated
* @return The Direction to <code>location</code> from this MapLocation.
* @return the Direction to <code>location</code> from this MapLocation
*
* @battlecode.doc.costlymethod
*/
Expand Down
22 changes: 12 additions & 10 deletions engine/src/main/battlecode/common/RobotController.java
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ public strictfp interface RobotController {
int getRoundNum();

/**
* Returns map width.
* Returns the width of the game map. Valid x coordinates range from
* 0 (inclusive) to the width (exclusive).
*
* @return the map width
*
Expand All @@ -35,7 +36,8 @@ public strictfp interface RobotController {
int getMapWidth();

/**
* Returns map height.
* Returns the height of the game map. Valid y coordinates range from
* 0 (inclusive) to the height (exclusive).
*
* @return the map height
*
Expand Down Expand Up @@ -369,9 +371,9 @@ public strictfp interface RobotController {

/**
* Returns the number of action cooldown turns remaining before this unit can act again.
* When this number is strictly less than GameConstants.COOLDOWN_LIMIT, isActionReady()
* When this number is strictly less than {@link GameConstants#COOLDOWN_LIMIT}, isActionReady()
* is true and the robot can act again. This number decreases by
* GameConstants.COOLDOWNS_PER_TURN every turn.
* {@link GameConstants#COOLDOWNS_PER_TURN} every turn.
*
* @return the number of action turns remaining before this unit can act again
*
Expand All @@ -390,9 +392,9 @@ public strictfp interface RobotController {

/**
* Returns the number of movement cooldown turns remaining before this unit can move again.
* When this number is strictly less than GameConstants.COOLDOWN_LIMIT, isMovementReady()
* When this number is strictly less than {@link GameConstants#COOLDOWN_LIMIT}, isMovementReady()
* is true and the robot can move again. This number decreases by
* GameConstants.COOLDOWNS_PER_TURN every turn.
* {@link GameConstants#COOLDOWNS_PER_TURN} every turn.
*
* @return the number of cooldown turns remaining before this unit can move again
*
Expand All @@ -414,9 +416,9 @@ public strictfp interface RobotController {

/**
* Returns the number of cooldown turns remaining before this unit can transform again.
* When this number is strictly less than GameConstants.COOLDOWN_LIMIT, isTransformReady()
* When this number is strictly less than {@link GameConstants#COOLDOWN_LIMIT}, isTransformReady()
* is true and the robot can transform again. This number decreases by
* GameConstants.COOLDOWNS_PER_TURN every turn.
* {@link GameConstants#COOLDOWNS_PER_TURN} every turn.
*
* @return the number of cooldown turns remaining before this unit can transform again
*
Expand Down Expand Up @@ -766,8 +768,8 @@ public strictfp interface RobotController {
// ***********************************

/**
* Sets the indicator string for this robot. Only the first
* GameConstants.INDICATOR_STRING_MAX_LENGTH characters are used.
* Sets the indicator string for this robot for debugging purposes. Only the first
* {@link GameConstants#INDICATOR_STRING_MAX_LENGTH} characters are used.
*
* @param string the indicator string this round
*
Expand Down
2 changes: 1 addition & 1 deletion engine/src/main/battlecode/common/RobotInfo.java
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package battlecode.common;

/**
* Struct that stores basic information that was 'sensed' of another Robot. This
* RobotInfo stores basic information that was 'sensed' of another Robot. This
* info is ephemeral and there is no guarantee any of it will remain the same
* between rounds.
*/
Expand Down
Loading

0 comments on commit 3c8b672

Please sign in to comment.