Currently Online

Latest Posts

Changes in GettingStarted

Editor Comment

Started 3D Graphics Section and made the page for more general use by adding sections for Language Translation, Website Development and Code Development


Revision Differences of Revision 20

# Getting Started as a Creator of Game Content ¶
_(under construction) started 19 Dec 2010_ ¶

Contents ¶
[TOC] ¶


## Introduction ¶
So you are interested in creating content for the project? __Great! Welcome!__ ¶

Whether you are a coder, graphic artist, musician, or web guru, there are some steps to take to get started as a productive participant. You may not be familiar with the development environment and tools used in the Widelands project, so this page is intended to outline what is needed by a creator of content. It CAN get a bit technical in places, but have courage, most of those tasks are one-time set-ups. (Remember that you are invited to post any questions you may have in the forums or the IRC Chat.) So let's dive in. :) ¶

## Launchpad.net ¶
All of the files that make up the source code, documentation, graphic and audio content of Widelands is maintained in one of three repositories ("trunks") on [Launchpad.net](https://launchpad.net) ¶

* __The main development ["trunk"](https://launchpad.net/widelands)__ - contains all of the application-related files, (i.e. everything that is needed short of a compiler and libraries to build and compile an executable version of the game.) ¶
* __The ["media trunk"](https://launchpad.net/widelands-media)__ - contains the graphic and audio sources used to generate Wideland's visual and audio content. ¶
* __The ["website trunk"](https://code.launchpad.net/widelands-website)__ - contains the code that supports this website. ¶

### Establishing a Launchpad.net Account ¶
Just as the main repositories are referred to as "trunks" on Launchpad, revisions from development are referred to as "branches". More on that later. ¶
While you don't need an account to download branches from Launchpad, a Launchpad.net account is required if you wish to effect any changes. ¶
[This link](https://help.launchpad.net/YourAccount/NewAccount) will take you to the Launchpad website page for setting up a new account. ¶

>__NOTE:__ If all of this technical mumbo jumbo is just TOO daunting, there are other avenues that can be taken for art, music and sound. It is just that by working directly with Launchpad, you eliminate a lot of extra work to prepare your creations for use in the game. It is the PREFERRED path, not the only one. Again, let us know if you are having challenges by posting something in the IRC Chat, Forums, or a message to the Elder of your choosing. :) ¶

### SSH Key Description and Use ¶
Launchpad trusts that you are who you claim to be. Later, such as when you're using the bug tracker's email interface, you'll need to use an electronic signature to prove your identity. ¶

A Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices, encrypting and decrypting the data to ensure it is received by the intended party and no one else. At the same time, it assures the recipient that they are dealing with whom they think they are. ¶

[This link](https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair) ¶
takes you to where the Launchpad site documents the process of setting up an SSH Key pair for use in Launchpad. ¶

## Launchpad Interaction with Bazaar ¶

### Description ¶
Well, with all of the program development projects that are housed on Launchpad.net, including our Widelands effort, there is a need to keep track of the changes/revisions that are constantly being made to the programs and content of all of those many projects. The Launchpad.net website utilizes a free OpenSource utility called Bazaar for the task of version control. It is through Bazaar (bzr) that all uploads and downloads to Launchpad are performed. Bazaar keeps track of every change that is made and "committed" (or finalized) to every branch and trunk. This allows changes from multiple developers to be merged without impacting another's work and it facilitates backing out changes that are not wanted. Yes, Bazaar has a lot to do and plays a very important role in keeping things manageable. :) ¶

### Bazaar Primer ¶
The BzrPrimer page is an excellent reference for getting started with Bazaar. It refers solely to the main development trunk (lp:widelands), but the media trunk (lp:widelands-media) and the website trunk (lp:widelands-website) are developed in the same way. (By the way, you have likely already guessed "lp" stands for Launchpad.) :D ¶

The bzr commands are well documented in manuals on the [Bazaar website](http://doc.bazaar.canonical.com). ¶

### Some Terms ¶
Here are some terms you may come across in the bzr documentation: ¶

* __trunk__ (or "tree") - the "official" collection of files that comprise the project. These files have all been reviewed and are considered acceptable for use in the program. ¶
* __branch__ - a folder of files under development. A branch can be a full copy of the trunk (created locally with the "bzr get" command) or a small subset of files currently being worked on. ¶
* __checkout__ - used to refer to a copy of the trunk or of another branch to review and/or work on locally on your machine ¶

> TIP: ___Qbzr___ - Is an optional utility (really an extension of bzr) that can be used in concert with Bazaar. It provides a graphical user interface (GUI) which makes log inquiries and other tasks a little easier. Here is a [Link](http://wiki.bazaar.canonical.com/QBzr) to its homepage. Windows users also have the option of [TortoiseBzr](http://wiki.bazaar.canonical.com/TortoiseBzr) which provides a GUI for use in the Windows operating system. ¶

## Media Trunk ¶
The Media Trunk (lp:widelands-media/trunk) contains files that were used to create the media used in the game. It is structured as follows: ¶

Folder | Sub-folder | Sub-sub-folder | Contents ¶
------ | ---------- | -------------- | -------- ¶
.bzr | | | files pertinent to version control (Do not modify) ¶
graphics | | | sources, tools and templates which support the graphic content ¶
| campaigns | | campaign art arranged by tribe ¶
| stock_sources | | ¶
| | blender_resources | materials, textures, and sundry .blend files for general 3D modeling ¶
| | blender_set_templates | empty templates with rendering stages for 3D models ¶
| | pngs | 2D images, loading images arranged by world ¶
| | structure_templates | template directories to organize new tribes and worlds ¶
| tools | | python scripts and quality control references ¶
| tribes | | 2D and .blend 3D sources of tribe-specific game art organized by tribe ¶
| user_interface | | 2D images for menus, icons, borders, etc. ¶
| wiki | | 2D art for the wiki ¶
| worlds | | 2D and .blend 3D sources of world-specific game art organized by world ¶
music | | | ¶
| src | | files which support the music content ¶
sounds | | | ¶
| src | | files which support the sounds content ¶

## Main Trunk ¶
The Main Trunk (lp:widelands/trunk) contains the files that go into building the executable version of the game. ¶
For our purposes, the following lists the Main Trunk folders which are of concern to content creators and a second list for your information of those folders with which a content creator rarely if ever may deal: ¶

__Folders of primary interest for content creators__ ¶

Folder | - | Contents ¶
------ | - | -------- ¶
global | | 2D game art common across tribes and worlds ¶
music | | .ogg music files used in the game ¶
pics | | 2D graphic files for the user interface and for general use on the game board ¶
sound | | non-music .ogg sound files that enhance game play ¶
tribes | | 2D game art specific to each tribe (worker and building animation, wares, frontiers, etc.) ¶
worlds | | 2D game art specific to certain worlds in the game (trees, animals, immovable objects, etc.) ¶

__Folders usually of no concern to content creators__ ¶

Folder | - | Contents ¶
------ | - | -------- ¶
.bzr | | files pertinent to version control (Do not modify) ¶
build | | for use by those packaging the game ¶
campaigns | | game maps for the campaigns ¶
cmake | | program coding tools ¶
compatibility | | contains savegame files of older official releases for archiving and testing purposes ¶
doc | | sundry documentation for developers ¶
fonts | | font sets used in the game ¶
maps | | game map files that are packaged with the game ¶
po | | files used in language translation ¶
scripting | | .lua files that provide criteria for game play and control ¶
src | | program source code of the game ¶
txts | | text files accessible by the player (tips, readme, etc.) ¶
utils | | python scripts and other files used by coders for testing, debugging, etc. ¶

## Graphics Development ¶
Everything from buttons to buildings, from windows to workers, in short everything that is visible with regard to Widelands falls into this category. ¶

### A Word About Style ¶
The overall style of Widelands aims for a "gentle" player experience. In visual terms, we attempt to achieve this through the use of muted colors and some softening of photo-realistic images. Careful attention also must be made in the use of colors that will not distract and clash with other screen elements. In other words, we try to keep it visually interesting without assaulting the player's senses. It should also go without saying that a consistent use of colors and patterns is very important to tie the player's experience into one cohesive whole. ¶

### Links to Existing Art-related Wiki Pages ¶

* WidelandsArtEthics - Do's and Don'ts ¶
* AboutColors - The use of Player Colors ¶
* BlenderPerspective - 3D Modeling ¶
* DevelopmentgameContent - Descriptions of tribes, story lines, etc. ¶
* GenericMovementSuggestions - A short brainstorm of animations ¶
* ImmovableProgramReference - WARNING: Technical Content :) ¶
* WorkerCommands - A short list of commands for worker conf files ¶
* CampaignUi - Explanation of the structure of campaigns in Widelands ¶
* TriggerAndEventsReference ¶
* [Productionsite Program Reference](http://widelands.svn.sourceforge.net/viewvc/widelands/trunk/doc/productionsite_program_reference.xhtml) - conf file commands for production sites ¶
* MarkupReferenceForRichtexts ¶


### 2D Graphic Development ¶
Every graphic, even those modeled in 3D, ends up as one (or more in the case of animations) 2D image by the time it is usable in the game. The predominant graphic file type in Widelands is PNG due to its lossless compressibility and support of alpha channels. Some jpeg files are used as loading scenes (pictures that are displayed on the screen while a game loads) due to their superior handling of photographic images. ¶

#### 2D Formats and Tools ¶
Any 2D graphics program may be used to create content as long as it can ultimately generate png or jpeg. Because neither png nor jpeg support multiple layers, the Media Trunk contains a large number of source files in the xcf format (native to the Open Source graphics tool [GIMP](http://www.gimp.org/).) Maintaining these original files as sources in the Media Trunk, makes future modifications to those images much easier. ¶

#### User Interface Graphics ¶
The User Interface, "UI", is that part of the game that conveys information to the player through logos, menus, pop-up windows, splash pages, etc. It also supports input from the player with buttons, check boxes, icons, and so on; and it makes the whole experience more pleasing to the eyes with backgrounds, borders, fonts and the like. When designing an element for the UI, strict attention must be given to the specific dimensions that have been coded for it by the programmer who has painstakingly plotted its placement in relation to other elements that will appear on the screen with it. ¶

#### 2D Game Graphics ¶
The purpose of any game, of course, is that it be played. Game graphics bring the playing experience "to life". Whether it is a building or a worker or the ground that they stand on, the visual representation of these elements must echo what has already been said about style and color. The scale of the game engine (i.e. the size of the playing elements on the screen) is such that great detail in a particular image can easily be lost when it is reduced to fit on the game board. So some shortcuts can be made when designing. But the fact that a worker can pass with balls for hands, brings with it the need to perhaps over-emphasize features that are desirable to be seen. (Is that a "fishing pole" or a "walking stick" that little guy is holding?) ¶

#### WL Editor 2D Graphics ¶
_Needs content_ ¶

### 3D Graphic Development ¶
_NWhile all of the images used in Widelands are 2D, animation is made much easier when rendered from a 3D model. With very few exceptions, the great majority of objects on t_he game board (indeed all of the animated ones) have their start as a 3D model.

#### 3D Modeling in Blender ¶
The 3D models (or "meshes") for Widelands are stored in the Media Trunk as .blend files. The .blend file format is native to the Open Source 3D modeling tool [Blender](http://www.blender.org/). Unlike some 3D modeling tools, Blender has a wide set of features that support everything from importing and modeling 3D meshes to generating fully rendered 2D images and animation. All of the .blend models in Widelands have been created and stored from [Blender version 2.49](http://www.blender.org/download/get-blender/).

#### Blender versionk 2.5x ¶
Development of Blender has certainly not stood still and beta version 2.55 has recently been made available for user testing. As tempting as it is
_Nto jump right into using the latest development release, we remain using version 2.49 for Widelands 3D files for two compelling reasons. First, Version 2.49 is Blender's most current "stable" version and for a developer having reliable tools is a "good thing". Secondly, the python script_s upon which we have come to strongly rely do not work in version 2.5+. So for now, we are staying with version 2.49. :)

#### The Templates ¶
_LA consistent appearance of the images on the game board is very important. It would look strange to see a building from one angle and another building next to it from a completely different angle, possibly with different light and shadow patterns as well. So everything on the playing field should be presented from the same specific camera angle and lighting. In other words, they should all be rendered on the same "stage". ¶

To make consistency of these elements as easy as possible, two "empty" .blend files exist as templates which the artist can use either right from the start as he/she creates the model or as stages into which the model can be appended and not have to worry about setting up the camera and lighting. ¶
These template files are: empty_building_template.blend and empty_worker_template.blend and can be found in the ~/graphics/stock_sources/blender_set_templates folder in the Media Trunk. ¶


#### The Scripts ¶
_List the python scripts in the tools directory and describe what they do_ ¶

#### Animation ¶
_Describe the process of animation as it is done for Widelands workers, buildings and other bobs_ ¶

### Conf Files for Graphic Elements ¶

#### Description ¶
Programmers can use many different methods to control how and when a program runs and provide it with information that can vary. In Widelands, one method we use are text files named "conf" which are associated with specific objects in the game. A conf file contains information to describe the object to a program and thereby allow that program to perform tasks that are common to many different objects. Conf files also can contain commands to control how the program performs those tasks. Because it is a plain text file, conf files can be edited or created by any text editor. ¶
> __NOTE:__ Care should be taken when editing conf files to prevent accidentally changing program control information that effects game play. ¶

A wide variety of objects have conf files associated with them, and in almost every case the conf file and the graphic files of the object(s) to which they refer are placed in the same folder, (or at least in the same directory path for collections of objects like worlds and tribes). ¶

Here is a list of graphic objects with which conf files are associated: ¶

* __workers__ including carriers, manufacturers, harvesters and soldiers ¶
* __wares__ ¶
* __buildings__ including production and harvesting sites, military sites and training sites ¶
* __critters__ (animals) ¶
* __trees__ ¶
* __immovable objects__ ¶
* __productive areas like farm fields and vineyards__ ¶

And as stated above, even tribes and worlds have their own conf files to describe their contents and environment. ¶

#### Artists and conf files ¶
Not all artists are coders, nor should they have to be, but there are some elements in a conf file for which the artist is responsible. ¶
Conf files that are associated with graphic objects like those listed above contain at least one animation section that specifies the graphic file(s) associated with the object. I'll call these _"animation sections"_ even if the object has only one graphic file, like a ware for instance. ¶
Let's take a look at some common parameters that the artist should know and can appear in an animation section. ¶
Section headers are always bracketed, e.g. __[walk]__, and parameters are listed on separate lines. ¶

##### Picture, Pics/Dirpics There is a difference. ¶
These parameters have a value that is the name of the object's graphic file. In the existence of multiple graphic files, a value will contain "wild card" place holders for the parts of the file name that differs. ¶
The __Picture__ parameter is often used with immovable objects and can appear anywhere in the object's conf file. ¶
The __Pics__ parameter is used in an animation section as is the __Dirpics__ parameter which is used when the images have more than one orientation such as walking east and west. ¶
> _Example 1:_ Picture=Stone1.png ¶
> _Example 2:_ Pics=Stone1.png ¶
> _Example 3:_ Pics=tree_??.png - which would point to tree_00.png, tree_01.png, tree_02.png, etc. ¶
> _Example 4:_ Dirpics=walkload_??_!!.png - points to walkload_00_e.png, walkload_00_se.png, etc. ¶

##### Hotspot ¶
Hotspots define a place on a graphic image through its x and y coordinates that can be used as a handle or reference point to provide control over positioning the image on the game board. ¶
For example Hotspots help carriers stay on the road and control how high or low, left or right they carry any wares. "x" coordinates are the number of pixels from the left edge of the image. "y" coordinates are the number of pixels from the top edge of the image. ¶
> _Example:_ hotspot=17 12 - where 17 is the x coordinate and 12 is the y coordinate ¶

##### playercolor ¶
The __playercolor__ parameter, when used, has a value of "true" to indicate the existence of playercolor mask files for the object. For more information on playercolor see the AboutColors page. ¶

##### fps ¶
The __fps__ parameter is used to specify the frame rate, i.e. playback speed, in frames per second of an animation. ¶
> _Example:_ fps=20 ¶

#### Buildings ¶
Conf files for buildings, depending on their nature, can contain many unique parameters. Most of which should not be adjusted by artists. ;) But buildings can have animation, of course. Hotspots for buildings denote where the road ends at the building. ¶

The following animation sections can be found common to all buildings: ¶
>* __[build]__ - this section defines the building's construction animation (usually 4 frames) ¶
>* __[idle]__ - this animation section depicts the building in a non-working or resting state ¶
>* __[working]__ - this section depicts the building in a productive working state ¶

As for those many other parameters that can be found in a building's conf file? Most of them control the building's influence on game play and can be found on the ConfFileCommands page. ¶

#### Worker Parameters ¶
Conf files for workers will also contain an [idle] animation section. (Hey, they have to rest sometime!) :D ¶
Other animation may also be represented in the following sections: ¶
>* __[walk]__ - ¶
>* __[walkload]__ - depicts the worker carrying a ware ¶

Special programs unique to certain workers can include these animation sections: ¶
>* __[hack]__ - used for lumberjacks and stonemasons (and occasionally programmers) ;) ¶
>* __[plant]__ - used for farmers, foresters, etc. ¶
>* __[harvest]__ ¶
>* __[breed]__ - like plant, but used for gamekeepers and fish_breeders ¶

Soldiers have these specific animation parameters for their unique battle graphics: ¶
>* attack_success_w= ¶
>* attack_success_e= ¶
>* attack_failure_e= ¶
>* attack_failure_w= ¶
>* evade_success_w= ¶
>* evade_success_e= ¶
>* evade_failure_e= ¶
>* evade_failure_w= ¶
>* die_w= ¶
>* die_e= ¶

Other programs unique to workers will be associated with their own animation sections. For more information, see the ConfFileCommands page. ¶



## Music & Sound Development ¶
See the AboutAudio page for details.

## Language Translation ¶
_Needs input_ ¶

## Website Development ¶
_Needs input_ ¶

## Code Development ¶
_Needs input_ ¶