Questions emerged while working on my console board game.

[Kristjan Toots]

Hello.
Since I know I'm going to have a lot of questions before I ever finish my project I kept this topic subject generic, so I can post my future questions here as well.
I am working on my project, which is available here Guidance appreciated: Designing a board game
I've started this project over and over couple of times now. Since I'm quite inexperienced I think I have been taking too big bites and that's the reason for all my troubles.

Quick introduction, to save you from reading my other thread:
I am trying to "computerize" a board game with different monsters and objects which reacts to one another on the battlefield. Took, Stephan van Hulst, advice and I'm trying to get the basics done. Representing the game in it's simplest form in some console representation before going to mess around with the GUI.

What I have so far:
Character class with fields for name, id and co-ordinates in the field
Battlefield class which is responsible for building an array (trying to represent the grid) and printing it out to the console like: [][][]
Controller class which should be responsible for adding different elements to the grid and moving them around in the field.

Now I have stumbled upon some questions I would like to clarify before going any further.

* I have a Game class to use it as a point where I kick everything off. I have something like this in there. For some reason, approaching like this doesn't feel right. Should I solve this somehow differently?

Character player = new Character();
Field field = new Field();
Controller controller = new Controller();
        
controller.addCharacter(Field.getBattlefield(), player);
field.printField();

* I define some standard parameters for player in the Character class constructor. My Field and Controller class constructors are empty. Should I try to call some methods or to set something in them?
Example:

 public Field()
    {
        printField(); 
    }

* At the moment I am using an array int[][] to represent the battlefield [][][] format. Where should I define this array and how should I go about doing different things with it (ex. adding new players to it). I have defined it in the Field class, as a static array.
To add players I grab the array reference by getter and pass it to the method in the Controller class which doesn't return anything. Am I going to the right direction by passing it around? Should I approach this somehow differently?

public void addCharacter(int[][] battlefield, Character player)
    {
        this.x = player.getX();
        this.y = player.getY();
        this.name = player.getName();

        battlefield[x][y] = (int) name;
    }

Thank for your time.

[Stephan van Hulst]

When I start a project, I start by designing the public API of my core package, the one that houses my model. It helps to design it from the top down. Here's an example:

package com.example.game;

/**
 * The game's main class. Each round the game will select players who can then
 * perform a turn. A player's turn starts by calling startTurn() and ends after
 * time has run out, or when endTurn() is invoked. This continues until the game
 * is over.
 */
public final class Game {

  /**
   * Creates a new game.
   */
  public Game(List<Player> players, BattleField field);

  /**
   * The players participating in this game.
   */
  public List<Player> getPlayers();

  /**
   * The battlefield on which this game is played.
   */
  public BattleField getBattleField();

  /**
   * The current round. Each active player gets a turn per round.
   */
  public int round();

  /**
   * The current player that is about to start a turn or busy performing one.
   */
  public Player currentPlayer();

  /**
   * The time left for the current turn in milliseconds.
   */
  public long timeLeft();

  /**
   * Starts the next turn and resets the timer.
   */
  public void startTurn();

  /**
   * Ends the turn in progress.
   */
  public void endTurn();

  /**
   * Returns whether this game is finished.
   */
  public boolean isGameOver();

  /**
   * The winner of this game, if the game is finished.
   */
  public Player winner();

  /**
   * A textual representation of this game.
   */
  @Override
  public String toString();
}

package com.example.game;

/**
 * Represents a battle field. A battle field is a grid; each cell has a terrain
 * type and is possibly occupied by a unit.
 */
public final class BattleField {
  
  /**
   * The width of this battle field.
   */
  public int width();
  
  /**
   * The height of this battle field.
   */
  public int height();
  
  /**
   * The terrain type at the given coordinates.
   */
  public Terrain getTerrain(int x, int y);
  
  /**
   * The unit that occupies the given coordinates.
   */
  public Unit getUnit(int x, int y);
  
  /**
   * A textual representation of this battle field.
   */
  @Override
  public String toString();

  /**
   * Use this class to build a battle field.
   */
  public static final class Builder {
    
    /**
     * Creates a builder that will build a battlefield with the given size.
     */
    public Builder(int width, int height);
    
    /**
     * The terrain that will make up the battlefield. Edit this array directly.
     */
    public Terrain[][] getTerrain();
    
    /**
     * The units that will occupy the battlefield. Edit this array directly.
     */
    public Unit[][] getUnits();
    
    /**
     * Validates the terrain and units, and builds the battle field.
     */
    public BattleField build();
  }
}

These are just two example classes in the same package. They currently only contain public methods and rough descriptions. These will help you to design other classes, like Unit and Player.
When you have a more complete view of the core package, you can work out the method contracts a little bit more. State invariants, pre- and post-conditions. For example, the build method of BattleField.Builder should require the two arrays to have the same width and height at the time the builder was created, and none of the cells in the terrain array may be null.

When you finished your first vision of the public API, you can start working on implementing the methods. The public API should contain only methods that you trust the outside world with. For instance, the BattleField class does not contain a public method setUnit(Unit,int,int); a cheating player may simply replace a unit of the enemy with one of itself. Instead, the battle field is formed by the builder, after which it is set in stone and can only be edited by trusted classes inside the package. For example, Unit may contain a public method move(int, int), which validates that its owner is indeed the player who has the turn and that the target square is empty. Then it invokes a package private method setUnit(Unit,int,int) in BattleField twice (on the origin and goal squares) to actually perform the move. BattleField *trusts* Unit to play nice. All classes in the same package trust each other to play nice and maintain class invariants.

So as you implement the public API, you will find yourself adding package private methods to classes. You will probably also add more public methods, because it's highly unlikely you'll think of everything right away. The most important thing is that you document pre- and post-conditions of your methods really well, even the package private ones, because they will allow you to avoid bugs as much as possible since its easier to reason about what your program does. The same goes for private helper methods, except you don't really have to validate the pre-conditions of the method.

[Campbell Ritchie]

It is dangerous to create a class called Character because there is already a class of that name in the java.lang package.