=== CANTROID README ===
--- 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
/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.
1. Make the desired changes in /dbgen/include and / or /dbgen/procedures.
2. Run /dbgen/generate.sh; 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
--- 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
* Constants use ALL_CAPS_WITH_UNDERSCORES
* 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.