Design and Requirements Documentation for Wombat

From WorldForgeWiki
Jump to: navigation, search

Wombat Requirements and Design

Created: July 15th, 2008 Authors: Kai Blin, Thomas Ingham

Mission Statement

The Worldforge Open Media Browser Artists Toolkit serves the needs of artists contributing to large scale projects such as video games and other large software initiatives requiring creative media. Developed as an open source initiative as part of the Worldforge project; particular focus is applied to the workflow and processes surrounding the development of content for massive games.


Wombat is licensed under the GNU GPLv2+ open source software license. It's goal is to become a standard platform for video game and media production teams universally. Tools and technology developed within Wombat will follow the form and function of popular websites and desktop software with similar goals. In addition to the standard components available to end-users such as "Assets", "Collections" and "Users", special attention will be applied to the production of asset packages compatible with open source initiatives. The basic flow of the application follows a group of users organized by a Project Leader who assigns tasks to the team of creative individuals on the team for production. Tasks follow a standard metaphor for production of any type and may have full specifications at each stage; or simple text descriptions for the creation of media assets. Users who are referred to or discover the site independently through project's marketing efforts may register themselves for an account and apply for membership in any open team. Alternatively they may create a new project of their own and begin assigning tasks to themselves; or advertise their project in the community for help in generating content. This single goal is what makes the Wombat project such a tantalizing concept for open source initiatives. Commonly, in reviewing systems which assist in the development of software one will find a lonely request for a "logo" or other type of media asset. Because these systems are targeted at developers and application programmers; there are few people that will see the advertised request for media; and fewer that can actually do anything about it. By providing the public with a common interface for generating requests, we have the ability to develop a community of talented creatives who have the ability to execute quickly on a standardized set of parameters to produce artistic content. As an additional bonus for users of the system; participants in projects can optionally have their work displayed in a simple gallery format which can serve as their independent portfolio. Later it may be discussed the possibility of opening an economic exchange or other service whereby artists can be paid for their work at no cost; or any number of other alternatives which could be built and deployed on top of the Wombat software by independent third parties. Development of Wombat is intended to be ongoing however, a usable system for the Worldforge project is expected by the first of January, 2009.



The foundations of the Wombat project are twofold. Firstly is a matter of basic version control for media files; which presents both usability as well as unique technical challenges. Second is the concept of centralization and workflow control for projects which, commonly, are being participated in through different time zones and often across language barriers.

Technical Problems

Because (as a general matter) most media file types are stored as binary data; they make poor players in the VCS (Version Control System) market space. Most VCS software will treat binary files as wholly self-contained assets and upon seeing that one has been updated; the entire copy of the file will be placed in the repository as a revision; this rather than as text might be stored only retaining the differences between the current version and the immediate ancestor to a given file. This increases exponentially the storage space required for media assets and can potentially cause problems in the workflow of code projects using VCS in that transfer times of the repository can be prohibitively long. Media files commonly include or reference other media files which are then instantiated in the encapsulating document only while the file is open in the default editor. This relationship is ignored completely by all VCS when in fact having ones subordinate files modified is incredibly meaningful to the document which encapsulates those assets. During the deployment of software which includes media that has been managed in a VCS, packaging of that media can be tedious due to the manner in which those files are both referenced by the final application binary; as well as the sheer volume of assets required to make, for instance, a video game. Commonly this task falls to a Technical Director or application developer to organize and package media assets.

Operational Problems

Traditionally artists utilize their local filesystems and perhaps some moderate form of file backup as a system to control revisions to the work they are preparing for production. This can lead to a lack of security because the quality of backups are entirely based on human error. Organizing a project as vast in scale as a massively multiplayer game of any type is daunting. Managers of projects are often the primary developers on their own project which leaves them with less time to manage a group of artists where all manner of barriers related to ken and knowledge make communication difficult. Version control systems include security features that are intended to ensure the validity of contributions and attribute sources where necessary. Interacting with tools dedicated to controlling multiple versions of files has a technical barrier which will need to be overcome to access the larger audience of capable artists and artisans in the public space.


Wombat is intended to be a component in the workflow of media creation for projects of all sizes. As such great care should be given to how well it participates in a variety of pipelines both now and into the future. In an effort to incorporate as many different work-styles and processes as possible an iterative deployment pattern is being developed focusing primarily on retention of assets; user authentication and task attribution.

The Desktop

An artist's desktop is sacred ground. Using their computer they create almost magical feats of visual delight. Wombat must interface at this level to remove any barriers to creativity. Therefore the present proposition is to utilize a DAV (Digital Access Volume) share to which they can connect and maintain file resources. Files stored in this volume are automatically version controlled transparently. All version control activity is available through the Wombat web UI for later annotation.

Third-Party Services

Services such as Launchpad and Sourceforge provide unique opportunities for the cases where Wombat housed media is to be employed for a project already using one of those systems. As Launchpad already provides an API for integration investigation should be done to incorporate Wombat control surfaces within the Launchpad UI or vice-versa.

Third Party Applications

As the platform gains prominence there will be a need to explore the implementation of more specific tools for each of the applications that artists commonly use to produce content for projects in Wombat. This may include a custom meta-data panel for Blender which links the work they are doing in a given session to the project information stored on the Wombat servers; or a plug-in for Gimp or Photoshop which allows them to interact directly with the Wombat service (ala Version Cue.)


Where possible it is desirable to be consistent with developing standards on the internet. This would include the problem of authentication and the maintenance of persistent accounts. OpenID is one standard gaining prominence and it's integration within Wombat should be explored in detail. One user, one login.


Because Wombat is an open source initiative it is essential to focus special attention on both marketing the collective artist base as well as positioning the tools to be accepted by a greater number of artists worldwide. While social bookmarking is quickly becoming the new "spam" it would be beneficial to the user-base to provide quick methods for cross-posting their updates to sites such as Digg, Reddit and Twitter where available.


Rules about the employment and use of all project assets in marketing and advertising as well as project participation. TBD

Web Application

The look and feel of the website is almost as important as it's function due to the proposed audience. In order to present the artwork within the repository in the most direct and efficient light a darker theme will be used consistent with applications such as a lightbox or photography viewer like commercial offerings from Apple (Aperture) and Lightroom (Adobe.) Graphical branding of the site should be kept stylized to help foster confidence in the tool using consistent user interface paradigms and effort should be applied to give the site an "Application" feel.


Marketing channels following initial launch will be... TBD


The messaging of all user manual and static content copy should be consistent with a single format. Wherever possible descriptions of the more complicated bits of functionality should be reduced to the simplest terms possible. This will aid in translation and ensure that the user experience as informed by any supporting documentation is consistent.

Artist Promotion

Artists can build portfolio pages which collect work they have contribute to. Portfolio pages serve as a "Profile" page for the user account upon which their highest ranked, or most discussed items appear. Artwork available in 2d form should be made visible through a simple slide viewer interface which provides access to large-format media downloads. Artists should have the option to affix their "tag" to images they take part in creating. Tagspace should be applied as a black footer to the bottom of images so as not to distort the overall image quality. Users of the site may leave open or anonymous comments on images seen in the portfolio of an artist; or they may sign up for an account and assist in tagging, describing or rating materials as the case may be.

Project Promotion

Projects can be promoted within the system by building promos. A promotional for a project can be constructed as a function of the media being created for the project; or as a composite added by the Project Lead. Promotional items aim to describe the main context of the project to incentivize others to participate. Promos appear as standard "advertising banners" where on some other sites one might see ads for retail software.



The system administrator group has access to all user records for maintaining the quality of the community through banning or some other system of demerit (as yet undesigned.) Administrators additionally have the ability to torpor projects which have reached a point of inactivity, send system update emails in addition to modifying the CMS portion of the site content: (FAQ, Help Manual, Blogs)

Project Lead

Project Leads are the centerpiece of all creative activity within the Wombat application. As projects are created by Project Leads, artists may be selected or apply for membership within a project and begin contributing media assets. Project Leads serve as moderators of the users in their project scope, have the ability to issue password reset requests on user accounts related to their project for minor support tasks and can submit bug reports to the Wombat dev team. Project Leads are also responsible for the generation of media packages once a project term concludes. Media packages are aggregates of media suitable for distribution and inclusion in game packages, installers, RPMs or other distribution types.


The bulk of the community is made up of Artists. Artists have the ability to create assets, apply updates to assets for version control, rate and describe assets within their project scope and offer assistance to others through the collaboration tools available in the application.


The general public is any non-authenticated user of the system. Public users have the ability to browse the site, search for assets and leave comments on artist profiles or asset description sheets.

Use Cases: Users and Authentication

User Registration

Users may register in one of two manners. The first and most likely is that they arrive at the site either through external direction or by browsing and wish to participate. These intakes are classified as "hard intakes" as the name implies they are more difficult to achieve. "Soft intakes" are instances where a Project Lead or Artist generates a request through the system to have someone join. In the primary case the user fills out a form and is then registered; able to participate in the community. In the second case, a Project Lead or Artist may send an "invite" to another person for which a link is distributed that shows the registration form; but also automatically adds the new user account to the project in question. New users must provide at least a working email address and a strong password for authentication. All other details are optional.

Modify (My) User Account

A user must be able to quickly modify their account details. The general practice is that there is a link on every screen in the application which displays the user details form to the user for immediate modification. Account updates for "My Account" should require verification of an original password. Additionally no account may be updated in such a way that the email address can be modified without being validated; or stricken entirely.

Modify A User Account

Administrators should be able to quickly modify or deactivate a user account for both security as well as continuity reasons. Administrators should be able to search through a list of user accounts where each line displays the status of the user, the nickname or email address of the user and a link to the edit screen for that account.

User Authentication

All registered users should have the ability to quickly authenticate themselves to the system. Where possible (and by user preference) a cookie should be stored for the client which bypasses the authentication screen on direct links into the system. Failed authentication attempts should display the status of the attempt to the user in the form of user feedback.

Password Request

If a user forgets their password they should be presented with a form which accepts an email address. Upon entering an active email address the system should deliver an email to the user containing a self-destructing link that is active for 24 hours and can only be clicked once. This link should take the user to a form where a new password may be entered. Successfully completing this process should leave the user in the logged in state; and on the screen for modifying their profile should they choose to set their password again; to something more known to them.

Use Cases: Community Activity

Contact Support

Every page in the application should contain a link that directs the user to a contact form where the user can enter suggestions, problems or kudos delivered to mail list.

Leave a Comment

Any user of the system (authenticated or not) should be able to leave a comment on an asset, project, or profile page. Comments made by non-authenticated users should be indicated as such visually distinct from authenticated users. Forms for leaving comments should be auto-populated if possible to include: Name and Date the comment is made.

Browse the Repository

The repository should be "browseable" from the top-down through Projects and then cascading through collections down to individual assets and their versions.

Search the Repository

Assets should be searchable by a simple string search that allows concatenation such that queries like: "All Images in Castlegard" would return a listing of all image (mime-type) assets in a project or collection matching Castlegard. Additionally the user should be able to apply a min and max date range on the search; or apply later sub-filters on results by collection (project, etc.) "All models by Ammon" would return assets created by or worked on by a user named "Ammon." Assets should be returned by default in order of modification date descending (newest first) unless the user specifies otherwise to view them by Alpha ASC/DESC, Modification ASC/DESC, Creation ASC/DESC, Activity ASC/DESC (# of keywords, comments and user participation), Rank ASC/DESC (user applied rankings.) Sort order should persist throughout the current session.

Qualify an Asset

Because we will be working with artistic, first generation content it is important to take care that all assets comply with respective copyrights or rules for application where possible. As such the "Qualification" of an asset can be performed by a user to indicate that an asset is thought to be unique; or does not violate any implied copyrights as known to the user. Qualification is not a required parameter but can help to ensure the integrity of the repository in a highly transparent manner.

Report Objectionable Content

Assets should include a companion value similar to "Rating" which indicate the appropriateness of the asset. Some users will be opposed to viewing images of naked humans, suggestive imagery or items considered pornography in some regions of the world. As a record is flagged objectionable by more users we gain the ability to limit the visibility of the asset. In the event that an asset is rated so low as to be clearly offensive; it can then be scheduled for removal from the system by an Administrator.

Use Cases: Project Management

Create a New Project

As a Project Lead, a user may request a form which allows the construction of a new Project in Wombat. Projects encapsulate tasks and instances of media assets; along with providing details about the purpose of the project, expected delivery dates or milestone schedules and other associated data. By default all projects require a unique Name, > 140 character description, and have a default status of "Open."

Modify a Project

Project Leads may modify any project they are affiliated with at the Project Lead level (multiple allowed.) Administrators may also view a list of projects that is searchable for modification via a simple form; or quick access to status changes. When the status of a project is modified, all Project Leads will receive notification via email of the event.

Create a New Needs List

Projects are a two-stage specification process; the first being the outlay and detail of a project through the creation of project header details and a set of "Needs" that must be met to complete the project. Needs lists are in principle a first-step toward work actually being completed. While the inclusion of assets in the project do not require a Needs list; projects which use them will likely have a higher level of success in a shorter time frame. A project may have any number of Needs Lists which itemize pieces of inventory that will be required for the successful completion of the project. A Need Item may be satisfied by the instancing of existing media; or by the creation of new media through a task or other activity. Need Items are specified as a: Name, Description, Media Type {Image, 3d Model, 3d Animation, 3d Composite, Audio File, Video File}.

Modify a Needs List

Needs Lists are modifiable until all of the items in the list have been satisfied. New Needs Items can be appended to the list and the state or status of a Needs List is automatically interpreted from the status of all Items in the list. Needs Lists are accessed through the Project view.

Create a Task Assignment

For Project Leads and Artists who require more structure, any Needs Item or request otherwise may be transformed into a Task. Tasks may be assigned in a forward-manner to a specific user in the project or, open and unassigned tasks may be claimed by any user in the project. Task assignments follow the same conventions as Needs Items with the addition of fields for: Due Date, Expected Work Time (Estimate) and Difficulty Level {1-5}.

Modify a Task Assignment

Tasks may be modified until they are assigned to a user. Once a Task is assigned; it is no longer modifiable and must be marked "deferred" or "cancelled" such that a new Task with the new information is created. The purpose of the static nature of Task items is to avoid confusion or the politics associated with changing specifications.

Claim a Task Assignment

Any user associated with a Project may claim an open, unassigned task. Tasks are searchable and sorted by Due Date ASC.

Revoke a Task Assignment

Project Leads may choose to revoke a task assignment once it has been assigned or claimed by a user. Tasks that have been revoked should retain information regarding to whom it was previously assigned. The revocation event should require that the user performing the revoke enter a brief description explaining why the task was revoked.

Decline a Task Assignment

If a user is assigned a task, they may optionally decline to accept the task. In the event that a user does decline a task; they should be required to enter a short description explaining why (Poor specs, No time, too difficult.) Once a task assignment has been declined it should move into the open, unassigned pool within the Project.

Create a Project Promotion

Project Promotions may be created by Project Leads to advertise their project throughout the application or on other websites. Promotions are widgets in the form of banners with absolutely specified URLs to the wombat system that originated them.

Disable a Project Promotion

Project Leads and Administrators have the ability to view all project promotions and selectively disable or enable them through a simple checkbox interface. Disabled promotions should appear nowhere in the site; the act of changing the status of a promotion should generate an email to the owner of the promo.

Use Cases: The Workbench

Add an Asset to the Workbench

Every authenticated user has a Workbench that may have multiple data-sets associated with it. The workbench is essentially a queue which may have assets associated with it. Assets in the workbench may then be acted upon en masse by the user for a variety of targets explained in further detail below. Each asset visible in the main workspace of the application should have a link which adds the asset to the workbench, in addition to the ability to drag assets directly into the workbench area at the bottom of the screen.

Remove an Asset from the Workbench

Assets in the workbench may be disassociated by either dragging the asset outside of the workbench using a pointing device or, by focusing on the asset in the workbench and choosing the "Remove" verb from the workbench menu.

Focus on an Asset in the Workbench

Assets displayed in the workbench may be "selected" by clicking on the icon of the asset in the list portion of the display. Focused assets may be ganged together for batch modification or selected one at a time. A single asset selected in the workbench will be displayed in full within the workbench for editing of relevant details based on user permission.

Add an Asset to the Repository

Assets may be added to the repository in a number of ways itemized here: 1. The user may upload a file to their Workbench through a simple form upload. Any number of files may be uploaded in a series. Files uploaded thusly can then be gang-selected and the "Make Asset" verb can be invoked from the workbench menu. This will bind all files together into a single asset that is then checked into the system for version control and collaboration. 2. The user may mount a DAV volume and access their user Share. Files can be added to this share directly, to be displayed similarly in the workbench. 3. ?? Regular version control methods.. ?? Additionally, an Asset may be created without a file present. This would be done in the case where more planning must be done or a dependency chain needs to be established to satisfy a goal where assets are not yet available.

Update an Asset in the Repository

By focusing on an asset in the workbench, the user may upload a new file to the asset. Upon a matching-name event, the old version of the file in the asset will be replaced in version control to maintain the history of the work performed on the asset. The user must also have the ability to tell Wombat that a file such as "kraken-002.png" is meant to replace "kraken-001.png" manually.

Delete an Asset from the Repository

Asset deletion is only available to Administrators. When an asset is removed from the repository a description explaining why is required.

Request a Review upon an Asset in the Repository

As assets have status flags in the database, a status flag for "Review Request" should be available to help artists get critique on their work. A special search results set should be available for viewing any assets at the current scope (Entire Repository, Project, Collection, Keyword: Rogue) which request review.

Append Keywords to an Asset

Focusing on an Asset in the workbench allows the user to append keywords to the asset. As a user adds keywords (either pre-existing or new words) to an asset a record should be maintained including [who] added [what keyword] to [which asset] [when].

Append a Description to an Asset

Descriptions are included in assets as a list of records to prevent overwriting of data in the chain. Descriptions are plain text, no html allowed text fields that include a date stamp for when the description was left.

Append a Rating to an Asset

Ratings may be applied to an asset for the current viewer. Similarly to keywords and descriptions, [who] [what] [which] and [when] should be retained.

Clone an Asset

An asset in the workbench may be cloned such that it retains the original artist information but may be modified independently of the version control for the source asset. Cloning can be one-directional; merging will not be required.

Create a Package from My Workbench

As assets are included in packages, specific care should be taken to note the version number at which the asset was included. Assets exist globally in Wombat and as such, new data may be applied to assets as time goes on so that only the older versions of Asset files are applicable in a given circumstance.

Store My Workbench

The contents of a workbench may be stored with a name to make it easily recognizable in lists. The asset contents of the workbench should be stored along with the current focus.

Share a Stored Workbench

After a workbench has been stored; it may be shared with any authenticated user in the application. Changes made to the workbench are persistent.

Access a Shared Workbench

Any workbench that has been shared may only be open by a single user at a time. As a workbench is shared with a user, an email notification is sent to the target user indicating the availability of the workbench "file."