CSE2102jSettlers2 is a project mainly written in Java, based on the GPL-3.0 license.
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.
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.
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).
(written for Eclipse 3.6, should be applicable to other versions with minor changes)
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
- 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.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.
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.
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.