Latest Posts

Changes in GraphicsDevelopment

Editor Comment

added link to widelands-media repo


Revision Differences of Revision 25

## 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. ¶

[TOC] ¶


### 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 :) ¶
* [Worker Programs](https://wl.widelands.org/docs/wl/autogen_tribes_worker_programs/) - Full list of commands for worker `init.lua` files with usage examples. ¶
* [[ CampaignUi ]] - Explanation of the structure of campaigns in Widelands ¶
* [[ LuaScripting ]] ¶
* [Productionsite Program Reference](https://wl.widelands.org/docs/wl/productionsite_program/) - init.lua 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 ¶
The graphics utilized in the Widelands Map Editor, aside from its User Interface graphics which it shares with the game engine, are housed in the ~/worlds folder of the main trunk. They fall into three basic categories: terrain textures, bobs and immovables. ¶

* __terrain textures__ - These are seamless 64x64 pixel png files that are used to paint the ground surface of the game maps. They are housed in the /pics folder of every world. They can even be animated to represent surfaces like water and lava. ¶

* __bobs__ - [definition](http://en.wikipedia.org/wiki/Blitter_object), in Widelands are virtually every object that can move around on the gameboard that isn't a worker. This, of course refers mostly to the "critters" (animals) that can populate a game map. ¶

* __immovables__ - in addition to objects like stones and trees that appear in the game, this category also includes indicators which map-makers use to represent player headquarters positions and resources such as coal and iron. Immovables can be animated for use in the game to show things like a burning building or tree leaves rustling in the wind. ¶


### 3D Graphic Development ¶
While 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 the 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](https://code.launchpad.net/widelands-media) 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://download.blender.org/release/Blender2.49b/). ¶

#### Blender version 2.5x ¶
Development of Blender has certainly not stood still and beta version 2.59 has recently been made available for user testing. As tempting as it is to 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 scripts upon which we have come to strongly rely do not work in version 2.5+. ¶
Version 2.49, though still our __PREFERRED__ 3D modeling tool, is swiftly becoming outmoded. We are currently making plans to migrate to the latest Blender version, but that migration depends on having a stable Python 3.x API in Blender and scripts to effect the bulk file conversion of our 2.49 models as well as scripts to replace those we currently use in animation and other tasks. ¶
So, as an interim approach until we can get Python 3.x scripting for the animation/conversion and evolve fully to Blender 2.5+, we WILL begin to accept development with the new releases of Blender with these conditions: ¶

* 1) 3D models (i.e. the .blend files) created by a version other than 2.49 __MUST__ be prefixed with the Blender version number as part of the file name, so they may be easily recognizable and not confused with the older files. (ex. 2.57_house.blend) ¶

* 2) 2D images and animation from Non-2.49 models that are being proposed for inclusion in the game __MUST__ be pushed to private branches on Launchpad.net and submitted through a proposal for merger unless previously approved by the Graphics Elder or another elder. ¶

* 3) Artists submitting Non-2.49 models will be held responsible for supporting their work until the bulk-conversion of the balance of the 2.49 models. Non-2.49 models whose artist will not provide support until that time may be removed/replaced with supported work. ¶

These conditions are subject to change as our experience dictates. ¶

Update: ¶

* The scripts are also working with Blender 2.79b, and even seem to work with 2.82. ¶
* Most models work with Blender 2.79b, but some may have glitches, [e.g. with the particle generator](https://www.widelands.org/forum/post/19400/). ¶
* Blender 2.8 breaks all models because it dropped the Blender Internal Render engine which the old models used, and the remaining Cycles and the new Eevee render engines need different materials and the lighting is also different. There are addons for Blender 2.79 to help converting the materials, but not the lights (info needed). ¶

#### The Templates ¶
A 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. ¶

#### Blender Materials and Textures ¶
Because much modeling work is done in folders outside of the Trunk, we request that ALL materials that are used in a model be embedded (i.e. not linked from an external library) and any 2D graphic images used for textures be packed with the model. (There is a button to toggle the packed status of the image at the right of the filename in the Image tab of the Blender Textures panel.) External libraries can be nice, however omissions can crop up if the material/texture is linked to other models where the library is not available. In other words, we like to see the .blend files as self-sufficient as possible regarding the materials used in them. Scripts are another matter as modifications to them have more wide-ranging impact. ¶

#### The Scripts ¶
Through Blender's Application Programming Interface, functions that are repetitive and/or common to some task can be scripted to run automatically. The following Python 2 scripts have been written for the Blender 2.4x API to automate the rendering of animation frames and their player color masks. They are housed in the ~/graphics/tools/ folder of the widelands-media repository: ¶

>__menu.py__ - automates the rendering process and displays a menu for specifying output destination, view direction, number of animation frames, etc. Calls the automask.py script if playercolor masking is requested. ¶

>__automask.py__ - generates playercolor masks for rendered models ¶

>__crop_animation.py__ - This script takes a list of conf files as arguments and crops ¶
the correponding animations to their proper size. This script needs updating to use the new init.lua file format. ¶

These next two scripts load the menu.py script from the graphics/tools directory of the widelands-media repository, so they need to have the /tools directory with its contents somewhere in the .blend file's tree. ¶

>__innerBuilding.py__ - calls the menu script for rendering building models and other models for which viewing is required from only one direction. (internal to empty_building_template.blend) ¶

>__innerWorker.py__ - calls the menu script for rendering standard models. It supports views of the rendered model from multiple directions. (internal to empty_worker_template.blend) ¶

This is what the menus created by __innerWorker.py__ look like in Blender 2.76b: ¶

[![blender_scripts_screenshot.png](/wlmedia/wlimages/blender_scripts_screenshot.png)](/wlmedia/wlimages/blender_scripts_screenshot.png) ¶

For a step-by-step guide on exporting animations, see [Getting the animations into Widelands](https://www.widelands.org/wiki/BlenderPerspective/#getting-the-animations-into-widelands) ¶

### Configuration Files for Graphic Elements and Animations ¶

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 configuration files named "init.lua" which are associated with specific objects in the game. A configuration 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. Configuration files also can contain commands to control how the program performs those tasks. Because it is a plain text file, .lua files can be edited or created by any text editor. ¶
> __NOTE:__ Care should be taken when editing .lua files to prevent accidentally changing program control information that effects game play. ¶

A wide variety of objects have configuration files associated with them, and in almost every case the init.lua 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 init.lua files are associated: ¶

* __workers__ including carriers, manufacturers, harvesters and soldiers, placed in `data/tribes/workers/` ¶
* __wares__ the raw materials and manufactured goods which are the basis for a tribe's economy, placed in `data/tribes/wares/` ¶
* __buildings__ including production and harvesting sites, military sites and training sites, placed in `data/tribes/buildings/` ¶
* __critters__ (animals), placed in `data/world/critters/` ¶
* __trees__, placed in `data/world/immovables/trees/` ¶
* __immovable objects__ like stones, ruins, fossils, etc., placed in `data/tribes/immovables/` ¶
* __productive areas like farm fields and vineyards__, placed in `data/tribes/immovables/` and `data/world/immovables/` ¶

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

Not all artists are coders, nor should they have to be, but there are some elements in an init.lua file for which the artist is responsible. Configuration files that are associated with graphic objects like those listed above contain at least one animation table that specifies the graphic file(s) associated with the object. See [Animations in our scripting reference](https://wl.widelands.org/docs/wl/animations/) for a description of the format.