README.developer - Notes and current status of 2011 JSettlers development (version 1.1.xx, running at nand.net)
	http://nand.net/jsettlers/devel/
	http://sourceforge.net/projects/jsettlers2/

Scroll down a bit for the current TODO list.
See VERSIONS.txt for recent changes.

CONTENTS
--------
- Overall structure of the code and project
- Tips for debugging
- Setup instructions for JSettlers as an Eclipse project
	(although you may use any IDE you want)
- Current partially-done work
- Current TODO list
- Coding Style
- CVS usage


Overall Structure
-----------------
The main server class is soc.server.SOCServer.
The client communication is soc.client.SOCPlayerClient, and in-game interface is in soc.client.SOCPlayerInterface.
Game state is held at the server in soc.game.SOCGame and its fields.  Partial game state is known at clients.
Communication is described in soc.message.SOCMessage.
Robots talk with the server like normal human clients.
Most robot messages are per-game; instead of being handled in SOCRobotClient,
these are handled in a loop in SOCRobotBrain.run().

Coding is done in Java 1.4 for now, but should compile cleanly in newer JDKs.
The build system is Ant, which is natively understood by Eclipse.  Use any IDE you want, including vi.
Use spaces, not tabs.  Please try to keep the other conventions of the code already there.
(See "Coding Style" below for more details.)

When adding new methods or fields, describe them in javadoc, including the @since marker
and the one-sentence summary (even though some old methods don't have that summary).

When submitting patches, please use unified diff (-ur) format.

For more information about the AI, please see Robert S Thomas' dissertation.
For more informaiton about the board coordinates, see the dissertation appendix A,
or javadocs in soc.game.SOCBoard, and src/docs/hexcoord.gif and hexcoord-6player.gif.


Tips for Debugging
------------------
You can use debug commands in any practice game, by typing into the game chat
textfield.  Type *help* for a list of commands.

If you want to inspect the game object state at the server or robot:
	Set a breakpoint at SOCServer.processDebugCommand, or at "case SOCMessage.GAMETEXTMSG"
	  send a text msg from a client (the chat textfield), and inspect the game obj at that point
	To inspect game state at robot, breakpoint robotcli.treat and send a text msg like *BOTLIST* or robot2:current-plans
	On non-Windows JVMs, you can print a stack trace / thread dump to the shell by sending SIGQUIT.

To use the "Free Placement" debug mode, type this debug command on your turn:
	*FREEPLACE* 1
You can now build and place pieces without consuming resources, by clicking
or right-clicking on the board.  (Don't use the "Buy" buttons for Free Placement.)
The placements must follow game rules, except that they cost no resources.
To place for another player, click their face icon.  You cannot remove a piece
once it is placed.

The placed pieces accumulate victory points for their players as normal, and
Longest Road is tracked.  If a player gets 10 VP total, the game will be over
when their turn arrives; your own player would win the game immediately.

To exit Free Placement mode, either click "Done" (which will end your turn) or
type this debug command:
	*FREEPLACE* 0
When exiting Free Placement mode during initial placement, all players must have
either 1 settlement and road, or at least 2 settlements and roads.  This allows
the game setup routines to work properly during this debug mode.  The current
player will be set to the first player (if 2+ settlements/roads placed) or the
last player (1 settlement placed).


Setup instructions for JSettlers as an Eclipse project
------------------------------------------------------
  (written for Eclipse 3.6, should be applicable to other versions with minor changes)

- choose File -> New -> Project... -> Java Project from Existing Ant Buildfile.
- Browse to jsettlers-1.1.xx-src/build.xml, select the "javac" task in target "compile".
- You'll need to build once before you run it, to create version.info from resources/version.info.in.

See below for how to set up the coding style in Eclipse.

In my Eclipse project, I've created these debug/run configurations for testing:

Java applet: soc.client.SOCPlayerClient
   width 600, height 340
   parameters: PORT = 44203

Java applications:
  cli-noargs  soc.client.SOCPlayerClient
  robot1      soc.robot.SOCRobotClient
     arguments: localhost 44203 robot1 r1
  robot2      soc.robot.SOCRobotClient
     arguments: localhost 44203 robot2 r2
  socserver   soc.server.SOCServer
     arguments: -o NT=t -o PL=5 -Djsettlers.startrobots=7 -Djsettlers.client.maxcreategames=2  44203 9 dbuser dbpass
  socserver-sqlite  soc.server.SOCServer
     arguments: -o NT=t -o NT=y -Djsettlers.db.url=jdbc:sqlite:jsettlers.sqlite  -Djsettlers.startrobots=7 44203 9 dbuser dbpass


Current partially-done work
---------------------------
	- Refactor SOCMessage classes to use templates
	- Support for other board encoding formats, or other board sizes
	- Some SOCMessage classes (SOCGames, SOCJoinGameRequest) accept objects like SOCGame and parse/create them;
	    over-the-network communication will always be strings only.


Current TODO list
-----------------
	Work on these items has not yet begun.
	Ranked from easier, to more difficult.
	You can also search the source for TODO for ideas.

	- User documentation is out of date; unsure if any user ever reads it anyway
	- Visual reminder to player when they've made an offer
	- Hovering mouse at center of robber-hex, should be able to see tooltip with the dice #.
		instead, currently see road of players on either side
	- Rename SOCGame.isLocal to .isPractice
	- Show # VP when choosing where to sit, if game is in progress
	- Keyboard shortcuts for "roll", "done" buttons
	- Occasionally an image does not re-scale when board is stretched.
		Instead of giving up (SOCBoardPanel.scaledHexFail, etc),
		try re-scaling again, but increase width or height by 1 pixel.
	- Kick robots if inactive but current player in game, assume they're buggy (use forceEndTurn)
	- If try to start server in JSettlers.jar, but port already in use, currently ends program immediately
		should instead show MessagePanel with option to practice, or even just show a message
	- Control the speed of robots in practice
		Adjust SOCRobotBrain.pause, ROBOT_FORCE_ENDTURN_TRADEOFFER_SECONDS, etc
	- Sound effects
	- Properties for game option defaults for server startup
		-Djsettlers.game.N7=y  instead of -O N7=y
		allow lowercase too
		probably best done at bottom of SOCServer.parseCmdline_DashedArgs
	- Possible: Auto-add robots when needed as server runs, with server active-game count
		only do it if jsettlers.startrobots property is set
	- At board reset, game observers not currently handled properly
	- Game "owner" with extra powers (kick out player, etc)
		what happens if owner loses connection?
	- "Hot seat" mode (multiple human players sharing a screen on 1 client)
	- Per-game thread/message queue at server (use SOCMessageForGame.getGame)
	- Seafarers support: Board coordinate-representation for larger board
	- Cities & Knights support
		- UI mock-ups
		- state change / network message plans
		- robot support
	- Refactor: combine the cli/displayless/robot endturn-like methods
		ex. search for ga.setCurrentDice(0), or newToOld, or ga.resetVoteClear
	- refactor: resource-type constants consolidate somewhere (Clay, Wheat, etc)
		current SOCResourceConstants.CLAY vs SOCPlayerElement.CLAY
	- refactor: name of dev-cards consolidate
	- refactor: SOCPlayerClient gui to separate class (mainpanel)

The rotated 3:1 port hexes' font is Optima Bold, 21 pt.


Coding Style
------------
This is the project's coding style, based on the original authors' style.
Although we may not agree with every detail of it, for consistency's sake,
please keep the conventions of the code that's already there.

Use spaces, not tabs.  The basic indent is 4.  Place braces on their own line.

Use 1 blank line between methods.  If you have nested classes, use 3 blank 
lines between them, and comment each one's closing brace with the class name.
If you have a long method whose work can be divided into "sections",
preface each section with a /** javadoc-style */ multi-line comment.

In emacs, you can place this in your .emacs file to use spaces instead of tabs:
(setq-default c-basic-offset 4)
(setq indent-tabs-mode nil)
	[ courtesy http://www.jwz.org/doc/tabs-vs-spaces.html, which also mentions vi ]
You will also want this to have this, which disables auto-reindenting:
(setq-default c-electric-flag nil)


Here's how to set up the coding style in Eclipse:

	preferences -> general -> editors -> text editors:
	[x] insert spaces for tabs
	displayed tab width: 8

	project properties -> java compiler -> configure workspace settings
	  compiler compliance level: 1.4

	prefs -> java -> code style -> formatter -> Click "Configure Project Specific Settings"
		{
		based on Eclipse built-in standard

		Profile name: 'jsettlers' (apply)

		(Indentation)
		Tab policy: Spaces only
		Indentation: 4
		Tab size: 8
		confirm is unchecked: [ ] Indent empty lines

		(Brace positions)
		All 'next line' except:
		Blocks in case stmt: Next line indented
		Array init: Next line indented
		[X] Keep empty array initializer on one line

		(Control Statements)
		[X] New line before else in if
		[X] New line before catch in try
		[X] New line before finally in try
		[ ] New line before while in do
		[X] Keep 'else if' on one line
		[ ] (all other options)

		(All other tabs)
		Take defaults

		}

		Hit OK
		Make sure the formatter "active profile" is jsettlers
		restart eclipse

		go to prefs -> java -> code style -> formatter
		  if it's not active: set active profile to jsettlers & restart eclipse

		prefs -> java -> editor -> typing
			Verify tab 8 spaces, indent 4 spaces:
	   [x] Tab key adjusts indentation of current line
	   "The tab display value (currently 8) and whether spaces are used to indent lines
	    are configured on the formatter preference page.  The current indentation size
	    is 4, using spaces."

When you hit enter and insert a new line in Eclipse, watch the whitespace, it
will add whitespace to the blank line to match the current indent.

If desired, in Eclipse preferences, you can bind a key combination to Remove Trailing Whitespace.
This will trim it from the entire file when the key is pressed.


CVS
---
HEAD recieves new features and enhancements for next 'minor' release.
As soon as a bug is fixed or a feature's design is fairly stable, it
should be committed to HEAD.

There are no branches, because jsettlers2 is mature at this point.
Each minor release is a stable release, there is no experimental branch.

Each release's files are tagged for the release:

$ cd JSettlers2
$ cvs -q tag release-1_1_12
$ cvs -q update -A

You can also see an overview of CVS commit comments in the CVS version
histories of src/java/resources/version.info.in and VERSIONS.txt.