--- Requirements ---
* mercurial (1.3.1 +)
* php 5.x
* mysql 5.x (with plans for porting to postgres)
* apache 2
* a unix-like hosting environment (windows may work with a few 
  adjustments). I use debian lenny x86.

--- Project organisation ---
/admin               administrator pages and scripts
/bin                 binaries: the C++ parts of the application
/code                various code that is used throughout the application 
                     and doesn't fit anywhere else
/cronjobs            scripts that implement time-triggered processes, intended
                     to be called by a cronjob.
/db                  the data access layer
/db/base             base classes for database objects, generated by 
                     dbgen. Do not hand-edit.
/db/generated        base classes for individual database entities,
                     also generated. Do not hand-edit.
/db/nudity           generated UI components for the various db entities.
                     Do not hand-edit.
/db/sql              generated SQL scripts. Do not hand-edit.
/db/test             generated unit tests. These may be edited, but I 
                     don't actively use them currently (although I know I
/db/user             this is where you add hand-written code for 
                     individual database objects. Each table and view has
                     two classes: TableName for the row, and 
                     TableNameCollection for the table.
/dbgen               definition of the database structure, for use with
                     dbgen, as well as scripts and utilities for db 
/general             out-of-game pages: public start page, login page
/maps                world map fragments (PNG and textfiles)
/nbproject           NetBeans project files
/play                in-game pages
/services            web services and map server
/settings            application settings, differ per deployment 
/static              static (and less static) content: css, images, 
/static/backgrounds  background images
/static/css          css stylesheets
/static/icons        various icons
/static/script       javascript
/templates           global HTML templates (master pages)
/test                playground for testing ideas etc.
/tools               development tools
/uc                  custom controls ("user controls")
/wiki                wiki pages (read, edit, search, contents, ...)

--- WebUI pages ---
WebUI is a library I wrote to facilitate writing web applications. It 
contains a control library, a templating engine, and a base class for web
In cantroid, each WebUI page is defined by a template (.html) and a code-
behind class (.php), both with the same base name, e.g. Login.html and 
Login.php. The BaseWebPage class automatically looks for the correct 
template and uses it. Additionally, a master template is used to provide
the markup common to all pages in a group; the master templates can be 
found in /templates.
The template file contains HTML markup, plus tags in two special 
namespaces, 'user:' and 'webui:'. 'user:' maps to controls defined inside
the cantroid project, e.g. user:DB_Nudity_UserPicker maps to 
/db/nudity/UserPicker.php. 'webui:' maps to standard controls defined in 
webui, e.g. webui:Button is a WebUI_Button. The base page automatically
creates controls based on its template and adds them to itself at 
run-time. To make the developer's life easier, the /tools folder contains
a php web page called 'HarvestControls.php' that can be used to extract 
all controls from a template and turn them into a phpdoc block which you 
can paste into your code-behind file to provide auto-completion in IDEs 
that support it.

--- How to change the database schema ---
The project is organized in a way that facilitates managing and deploying
database changes, and to keep code and database synchronized. This, 
however, requires that you do not touch the database directly, but instead
edit the database definitions (in /dbgen). The definitions are grouped by
functionality, with one .json file per group in /dbgen/include. Stored 
procedures are in /dbgen/procedures. All files in these two directories 
are automatically included by the generator script.

General procedure:
1. Make the desired changes in /dbgen/include and / or /dbgen/procedures.
2. Run /dbgen/; this will rebuild the generated code, and add
   stubs for new objects where needed.
3. Edit the generated stubs (in /db/user) where required to provide custom
4. From a web browser, run the database upgrade tool, e.g.:
   Clicking [Go] should produce a listing of SQL statements and the status
   message "OK". (If it doesn't, restore the database from a backup).
5. Using phpmyadmin or the CLI mysql client, verify that the database 
   looks as intended.

Some things to look out for:
* the upgrade script will add new columns and tables, but it will never 
  do anything that could cause data loss. The following operations need to
  be executed by hand:
  - renaming tables
  - renaming columns
  - changing the type (including nullability, size, and collation) of a 
  - dropping tables
  - dropping columns
  However, changing foreign keys and primary keys is supported, since the
  script simply removes all keys before doing its thing and then 
  reinstates the desired keys when done.
* there isn't much error checking - if you make a mistake in the json, the
  generator might exit prematurely without generating anything, it may
  output invalid code, or it may produce code that runs, but contains 
  invalid SQL.

--- Coding Conventions / Style Guide ---
* Curly brackets open on the same line as the preceding statement, close on a
  new line. The opening bracket is always preceded by a single space.
* Regular brackets open and close inline without any whitespace.
* Indentation uses tabs, not spaces. Spaces are used for alignment though.

* Classes and namespaces use PascalCase
* Variables, properties and functions (all kinds) use camelCase
* Exception to the above: properties in DB_Database that represent tables use
  PascalCase (this needs to be changed in dbgen some time).
* Private variables use _camelCaseWithPrecedingUnderscore
* In PascalCase, abbreviations up to two characters are all-uppercase; three
  and more characters are treated like a regular word. Examples:
  DBConnection (DB = 2 chars), SqlStatement (SQL = 3 chars).
* Tables, views, columns, routines and all other database objects use
  lower_case_with_underscores (this appears to be most compatible across SQL
  dialects and storage engines). The dbgen mapper maps these to PHP entities
  named according to the conventions above, so a column unit_type_code in
  table item_type maps to DB_ItemType->unitTypeCode.

PHP doesn't provide namespaces as of yet (5.1). To emulate a similar
behaviour, the following conventions are used:
* Namespaces are prepended to class names, separated with underscores.
* The code file's name does not contain the namespaces
* The project's directory structure follows the namespaces, but uses lowercase
  names for directories while the namespaces use PascalCasing
* Special case: the namespace WebUI maps to the WebUI library's source path
  (../lib/WebUI/src in the default configuration)
* Special case: code-behind classes for WebUI pages do not need to use a
* Special case: other classes without a namespace are in /code

* Doc comments use phpdoc syntax.