This media structure was presented and discussed at the latest media meeting, and seemed to be generally agreed on. Further refinement is needed in the more detailed directory structure (see directory outline at the end).

The discussion can be found here:

This document is also available in CVS at content\media\text\public\proposals\media_directory_structure.txt

It should also be listed at

Version History

2002-04-22 zzorn Hans Häggström First version, based on IRC discussion.


This document presents a proposal for a media cvs structure that tries to meet the needs of both artists and media users. It presents the goals of the structure, proposes two cvs media modules (media and media-original).

Next, a directory structure largely shared by both modules is presented, and each level of the structure explained in more detail. Next there are two notes about the independence of models and skin textures, and about the organization of the author information for media items.

Finally a preliminary outline of the whole structure is presented, with embedded comments and open questions.


The goals of this structure is to: Make things easy to find by creating a logical and intuitive directory structure Ensure that each media item has one and only one logical place Keep the hierarchy as low as possible, while still keeping the number of files and subdirectories in a directory manageable (around 20). Support the workflow of media creation by allowing supportive files like orthographical sketches to be stored with models. * Avoid end users and client developers from having to download unnecessary files by having two media modules, one for the original source images and supporting files, and one for the final media files used by clients.

CVS Modules

We have two cvs modules: media - This module contains the ready to use media, and is what clients use. It should contain no files that are not needed by clients or the server. media-originals - This contains original source versions of the media, along with any additional supporting files, concept sketches, etc.

Both modules have the same directory structure, except media has some directories left out (such as resources).

In addition things like aliases might be used to define subsets for graphical artists / musicians, etc. if necessary.

Directory Structure

The directory structure in each CVS media module is:


<> denotes required directory level, [] denotes optional directory level.

Explanation of each directory level follows.


Media_type is the type of the media, or purpose of it. The directories at this level are :

There are no 2d or 3d directories (models, textures, sprites, etc are a more useful subdivision), nor sketches (concept sketches are stored with the media item that they are concepts for, and general sketches can be stored in the illustrations directory).


Media_subtype is used in media_type directories that can be divided further up based on clear differences in how the media is used. For example, we could have sprites/iso, and sprites/topdown, for sprites rendered in isometric and topdown perspectives. We might also divide textures up in textures/materials, textures/skins, textures/building_materials, and textures/environment_maps Resources would have resources/picture_tubes (or whatever we choose to call them), and perahps resources/textures

Some media_types do not need a subdivision into subtypes, such as perhaps the models and illustrations media_types.


Category is an optional level to subdivide the media items in conceptual categories. It is some kind of logical subdivision, like sprites/iso/animals, sprites/iso/plants, sprites/iso/tools, sprites/iso/weapons, sprites/iso/cloths, sprites/iso/other_items, sprites/iso/building_elements, and so on.

We should be able to get away with just one category level, if we have around 20 categories or so, and each contain 20 items, we can store 400 items. That should be enough initially.

So there is no need to create deeper category hierarchies, instead the categories should be chosen carefully so that they subdivide the set of all media items of that media_subtype in about equally sized classes, with minimal overlap and maximal coverage.

media_item_category """""""""""""""""""""""""

Media_item_category is used to group together variants or subspecies of a media item, like dipvira_grassland, dipvira_forest, or human_male_muscular, human_male_skinny, human_female, human_child, etc.

This directory can also contain files that are shared between all the variants.

media_item """""""""""""

Media_item is the final directory level. It is used to store all the working files for a specific media product in the media-original module, and all the produced files for a media product in the media module.

media_files """""""""""""

A media_item directory for the grassland dipvira under models/races/dipvira/grassland in the media-originals module for example could contain: dipvira_grassland.3ds, dipvira_mesh_map.png, dipvira_grassland_concept_1.png, dipvira_screenshot_02.png, dipvira_screenshot_07.png, authors.txt, readme.txt, dipvira_grassland_preview.wrml, etc.

The models media_type tree would contain mostly orthographical concept sketches and other concept sketches aimed primarily to be supportive files for the modeling process of a media item. More general concept sketches and artwork that could be useful in other places too and not only for the modeling process can be stored in the illustrations media_type directory.

Note that the skin for the dipvira would be stored in textures/skins/races/dipvira instead of in the model directory. (See note below).

Note about models and textures """""""""""""""""""""""""""""""""""""

Models and textures are independent. A model can be used with many textures (different variations in coloring, patterns, age, etc), and a texture can be used with many models (the goal is to make for example humanoids all use the same texture mapping, so that cloth and other textures can be used for all humanoids without change. In the case of dipviras, the different variants (grassland, forest, and arctic) could use the same textures mappings, so if we create cloth textures, wound textures, etc for dipviras those can be used for all of them) ).

So it's a many to many relation, and neither can be inside the other. The only way to solve it is to put models and textures in separate places, and when a 3D model is to be shown in game, the server tells the client what model and what texture to use.

However, there could still be for example a models/races/dipvira/grassland/dipvira_grassland_preview.wrml file that would contain links to one of the textures, so it could be used to preview the model with one example texture.

Note about author information """""""""""""""""""""""""""""""""""

The files in a media_item directory should include an authors.txt file that lists the authors, their name, CVS user name, email, and how they have contributed to the media item. A structured machine readable syntax should be used, so that the information can be extracted for use in clients.

A separate directory with a file with more information about each author could be stored at the top level in each media module (media-originals/authors/). The files for each author would be named after the CVS user name of the author, and contain name, IRC nick, email address(es), homepage url, and an optional comment by the author (could be used for a short biography, presentation, or similar by the author). This makes it easier to store up to date email addresses for example, as well as other general data.

The authors.txt files, as well as the contents of media-originals/authors/ should be automatically or manually copied from media-originals to the media module, so that clients can utilize the information. Care should be taken to make sure emails can not easily be harvested by spam bots, however.

A readme.txt can optionally also be included in each media_item directory, with various notes relevant to maintainers and users of the media item.

There is hopefully no need to keep a copy of GPL and GFDL in every media item directory, instead they could be kept at the root module level.

Directory Outline """"""""""""""""""""

Here's an outline of the directory structure, with some parts sketched out. Uncertain items are marked with a question mark.