Wikiup White Paper (2nd Draft)
This is the second official draft of the Wikiup white paper. The original draft is still available here.
Introduction to ‘The Wikiup Games Project’
What is a wikiup?
Possible applications and concepts
Features which define a wikiup
Creating classes
Draft implementation for the Wikiup Core Service
Common concerns with the Wikiup model, and solutions
Why ‘Wikiup’?
Why aren’t you using <insert my favorite
technology here>?
Introduction to ‘The Wikiup Games Project’
The Wikiup Games Project seeks to change the fundamental development process of games by capturing and retaining user-generated content and making that content useful to a broad range of developers. Instead of assuming all games start from zero, Wikiup allows each game to build on top of existing content, and in turn provide a foundation for work that follows.
The theory is that the library of data will progressively improve as authors collaborate, rate each other’s work, and build on top of each other’s successes.
The following are the components of the service we seek to build:
Wikiup Core Service
The Wikiup Core Service is the base service offered by The Wikiup Games Project. It is a wiki-like library of game content, including – though not necessarily limited to – parameter data for game entities (e.g., a character, a weapon, a vehicle, or a map), sound and image data, and rule sets called “contracts”. All this content can be edited using the Wikiup Entity Explorer (see below), and is available either at or before runtime for client games, by way of an XML API. Client keys will be issued for use by specific applications.
Development of the Core Service will be done using MySQL and either PHP or Ruby or possibly both, to facilitate broader distribution of the Wikiup Deployment Kit (see below).
Wikiup Entity Explorer (WEE)
A Flex-based application for viewing and editing wikiup content via the wikiup
API. The explorer will have at least two basic states: explore and edit. Explore
will allow a user to traverse the library using parent-chld relationships to
see the interconnection of Classes. Edit will allow a user to edit the content
of a specific class and post changes back to the server DB. Note that the Wikiup
System has an API accessible to any client technology, so third party editors
(whether browser or desktop based) are simply a matter of someone choosing
to build them.
Wungeon
Wungeon will be the first game written as a Wikiup client. Developed in Adobe Flash (Flash Player 10, Actionscript 3), then hopefully ported to the iPhone, Wungeon will leverage the Wikiup API to create a full-featured adventure game. Wungeon is designed around the Wikiup concept: players will be able to create their own “kingdoms” using the Wikiup Entity Editor. Every kingdom is connected to several others, so players can journey infinitely from kingdom to kingdom in search of adventure.
Wungeon is one avenue being considered for revenue generation. While content authoring will always be free on the Core Service, Wungeon may be sold for a nominal fee, and several advanced features (including owning your own kingdom) will be purchased for a similarly nominal upgrade charge.
Wikiup Deployment Kit
The Wikiup Deployment Kit is a package of PHP files and MySQL instruction sets for deploying a Wikiup. In principle, anyone who can utilize these technologies on their web server (which is just about everyone) can deploy an instance of the Wikiup service.
It is our hope to license the Deployment Kit. Educators and students would be able to obtain free copies. Commercial developers could purchase licenses for a fee.
What is a wikiup?
A wikiup is a system for collaboratively authoring content, similar to a wiki. But whereas wikis usually focus on qualitative content, wikiups concern themselves much more with quantitative information. That is, values which can drive systems, such as games. A wikiup is not itself a game system or a game: it is a library of game data, completely separated from any specific game implementation. The information in the library is available to client applications through the Wikiup API.
This notion of separating data from the display of data is a common current in modern programming (e.g., XML); freed from the specific requirements of any particular implementation, content can be edited, shifted and re-purposed for a multitude of uses.
How is this useful? Well, consider a game that needs a host of characters, environments, weapons and other objects. In a traditional game development situation, the development team spends weeks authoring all these aspects of the game. Then the game has to be shipped, complete with all that custom data. While there’s nothing wrong with that approach, it requires a lot of development time, a lot of consideration about what each character or weapon or environment is like, and a lot of redundant conceptual work.
The Wikiup approach suggests that a team – maybe even a population at large – collaboratively develops the quantitative content that defines all these objects. Just as a population contributes to Wikipedia to author a collaborative encyclopedia, so do the users of a Wikiup jointly develop the content of a game universe.
To see the utility, picture a Wikiup detailing the particulars of a Dungeons & Dragons-style environment. For characters, we need knights, elves, demons, dragons, wizards, clerics, unicorns and faeries. For environments, we need dungeons (of course!), mountain caves and subterranean lairs, wastelands and deserts, towns, houses, rooms and shops. We need swords, maces, shields, chairs, tables, ropes, gold pieces, food, magic amulets and cursed artifacts. We need these and an infinitude of other odds and sods. The more of these we have, the richer our game potentially becomes. And each of these characters, each of these places, each of these objects requires a set of properties and actions to define who it is, what it does, how it behaves. In the traditional development approach, every game developer or team must define these things: a long, complex process. But if the game developer can simply reference an existing library – one which a large population has developed and vetted – a lot of the work is taken care of. More than that, this single library can potentially serve as a source for endless implementations of the general game type.
Consider the following two charts. Both look at the Wikiup content system from differing perspectives.
The first chart (Image 1) is from the perspective of a Wikiup deployment. A community of content authors uses either the Entity Editor or other 3rd party tools (anything that can speak coherently to the Wikiup API) to create content, stored in the Wikiup DB. Any number of client games may access the data to populate their games. Some may choose to employ other web services or even other Wikiups to implement a game that satisfies their needs.
 |
|
Image 1. Content creation and use model – wikiup |
 |
| Image 2. Content creation and use model - client game perspective. A client game draws data via the API using filters to get only approved information. Optionally, the game may have a local wikiup (local to the client or the client’s server) for storing game instance and player data. |
The second chart (Image 2) looks at deployment from the perspective of the client game. It shows essentially the same story, but notice two things. First, from the game developer’s perspective, the content authors are far removed. The developer may or may not care about this authoring community, but from her perspective, she simply receives a flow of data, without needing to worry particularly about how it came into being. Secondly, note that we’ve added a piece: another database listed as “local/server storage”. This points out that the developer can deploy a purely local Wikiup that only her organisation has access to. This allows her to add custom, even proprietary, data, while still accessing the larger game sphere. One use for this local storage would be to store instance variables, such as the health or wealth of specific character instances. Having local game data that follows the conventions of the larger Wikiup can simplify development.
Possible applications and concepts
Wikiups have a number of possible uses, both inside and outside of traditional gaming, including:
- Rapid game prototyping: the content library provides a ready store of vetted content with which to test new concepts rapidly.
- Game mashups: a game client could subscribe to multiple Wikiups to create bizarre game combos: dinosaur-superhero-Jedi battles, anyone?
- Data-driven knowledge banks/scientific simulations/modeling systems: there’s no reason to believe that the utility of a collaborative data system ends with games. Physics simulations and collaborative 3D modeling environments are an obvious example.
- Educational gaming: this is an area we’re keen to explore. Some research suggests that students may learn and retain curricular content better if they participate in authoring related game content. For example, a student learning history might author battle simulations based on actual historical events, and thereby improve their understanding of the events they seek to model.
Features which define a Wikiup
Rules/Structure
Like a BBS, the system will have an administrator who can define roles for the user base (users, mods, co-admins, etc). The administrator may define levels of exclusivity, depending on the needs of the Wikiup.
A Wikiup may be ‘free’ (requiring no approval before changes are accepted), ‘open’ (accepts changes with certain review procedures, such as sign-off by a moderator), or ‘closed’ (no changes accepted, to accommodate feature freezing, if required).
A Wikiup should have a member list (possibly requiring a password to join), but it should also have the facility to be open to anyone, at the discretion of the admin. There should be a provision to ban users and block certain IPs or IP ranges. Ultimately, a full-featured Wikiup should probably contain all the features of a BBS, coupled with the features of a wiki.
Database
A MySQL DB will hold content.
User Interface
The Wikiup API will be made up of a set of PHP-driven methods. The current plan for the Wikiup Entity Editor is for it to be a Flex-based application, but this is simply a window onto the API. As with other web services, development of third party content editors will be encouraged.
A typical entity within the Wikiup – a Class, as programmers would have it – is displayed as a form that lists the current Class, the classes from which the current one descends and is composed, the editable properties of the Class, and a descriptive space. There might also be room for pictures. It should be noted that pictures and description are basically window dressing: they help clarify the nature of the Class being described, but the practical application of the Class is usually tied up in the numerical data. (Such descriptives are nevertheless useful, as they help qualitatively communicate the intent of each Class.)
Hierarchical Class Structure
All classes subclass from one of the base classes, and can in turn be sub-classed
from. For example:
Wikiup (core class) > Character > Dragon > Red Dragon > Fenric, King of Red Dragons
Wikiup (core class) > Location > Room > Prison Room > Cell > Grimy, Blood-Stained Cell
A final keyword may well be part of the implementation. If set, the Object is no longer a class, but a unique instance. Fenric, above, is a good case in point. Presumably there is only one Fenric (or Frodo or Luke Skywalker or Berek Halfhand) and the ‘class’ should therefore never be sub-classed.
Compositional Class Structure
All classes (except base classes) can be composited to create variety through composition (see Creating Classes, below).
All Wikiups have a core class called Wikiup, from which all other classes descend directly or indirectly. By inheriting from Wikiup, all classes gain the inherent properties of a Wikiup (see Wikiup Core Class, below), and may, in fact, be thought of as smaller Wikiups unto themselves. The administrator creates a set of further base classes (all direct descendents of Wikiup). All classes within that Wikiup would descend (directly or indirectly) from one of these base classes.
Core and Base Classes
 |
| Image 3. A possible Class tree. Wikiup is the core class from which all others descend. The base classes are the first level of extension: central conceptual blocks that broadly define most aspects of any game. Descending from each of the base classes, we begin to get apply greater and greater specificity. I’ve shown a small number of character descendents to convey the concept, but of course the number of descendants is limited only by the imagination. |
For a game implementation, the following might define the set of base classes.
Wikiup Core Class: The core class from which all others descend. Importantly, the Wikiup class has a property called edit which defines a value (0-100) indicating who can edit it. This approval key can be independently set on any descending class (thus, everything) for the purpose of freezing out users below a certain level.
Location: Base class for describing place.
Character: Base class for describing animate Objects.
Thing: Base class for describing inanimate Objects.
Ability: Base class for defining what something does. One never instantiates anything descended from Ability. Rather, Ability extensions are used compositionally to define the abilities of other classes.
Property: Base class for individual properties (e.g., strength, intelligence, air speed, wobble). Numerical properties should have min and max values, but some properties may be defined by Booleans, strings or other value types. Again, used only compositionally.
XML API
A call to the Wikiup returns an XML object containing the pertinent details of the requested library entity. How detailed this entity needs to be, and how configurable the request can be, are questions for further consideration.
What is certain is that calls for specific entities will allow for filtering based on reputation information.
The API itself will probably be largely RESTful, with RPC methods to read and write according to specific tasks, particularly filtering. Ideas around the API are still in flux, however, so this may change.
Multiple versions, Contracts and the Reputation System
One extremely important difference between a wiki like Wikipedia and a Wikiup is that a Wikiup does not understand the notion of a ‘correct’ entry. Certainly an encyclopedia must understand the difference between right and wrong. The Battle of Waterloo was either in 1815 or it was not, and an entry stating 1816 or 1915 is incorrect and must be amended. In a game system, however, a bullet may do 20 points of damage, 50 points, or 1000 points, and for a specific implementation any of those answers might be correct. It is therefore fundamental to client stability that an entry, once created, remains permanently available within the system.
But this doesn’t mean that all entries are equal. Client games can differentiate between versions is several ways. The two most important are by using Contracts and Reputation.
Contracts
A “contract” is a set of rules, just like any legal contract; only in this case the rules we’re defining are the property rules by which a game’s content must abide (programmers might want to think of “contract” as a synonym for “interface”). Each version of a Class is assigned a contract and each client game declares the contract within which it operates. The contract defines the requirements of a character, an object, a location, etc. within a given gaming environment. A client declaring a given contract is never handed data which fails to fulfill that contract, thus client games – even ones allowing dynamically generated content – are never handed content which will break their code. The content may be of poor quality, but that’s where we get into reputation, below.
Contracts offer a number of other advantages, such as making authoring easier by filtering the properties a content author needs to deal with in the WEE, and offering the prospect of gaming “rings” consisting of contracted games. In principle, any character subscribing to a given contract should be able to move from game to game, regardless of the game’s author.
Reputation
Users of the Wikiup system can rate the work of other users, thus establishing a reputation for each participant. This reputation provides several ways for client game systems to filter data. Consider the figure below that defines a Class called Berserker.
 |
| Image 4. Alternate ways of filtering using reputation. The entry by amanda94 is more highly rated, but lazyboy has a higher rating overall. The client game may use either of these reputation markers as a means of determining preferred content, or it may dispense with reputation altogether and simply choose to accept usernames it trusts. |
There are several entries for this class. For simplicity’s sake, we’re showing just a few properties. But note the ‘Rating’ property. The best-rated entry is by amanda94. So a game creator could request the best-rated version of the Class, thus receiving amanda94’s entry. Alternatively, the game creator could ask for the latest entry by the best-rated user. The entry by lazyboy was not rated quite as highly as amanda94’s version, but lazyboy is rated highly overall, so the game creator knows he’s getting the work of a generally reliable author.
Another API call could tag a specific user. If the game author is the user tipperary, he mightn’t care what other users think of his work. He simply wants to get his version of the class. Fair enough, he can have it without inconveniencing anyone but the players of his own game.
Thus reputation serves the needs of author (better reputation), game developer (better data), player (better game play) and the larger community (overall better library).
Creating Classes
All Objects in a Wikiup are created either by a combination of inheritance and composition, or by inheritance alone.
Inheritance and composition are both methods by which one Class takes on the properties of another. The Wikiup object system enforces the rule that all Objects are part of an object chain, descending from a single base Wikiup class. For the purpose of the Wikiup, the distinction between inheritance and composition can be thought of as an “is” vs. “has/can” quality. If an item “is” a thing, it inherits the qualities of that thing. For example, a penguin is a bird, so a penguin inherits all the properties of a bird. A rock hopper penguin inherits in turn from penguin.
Composition comes in when we start defining the abilities and possessions of an object. For example, the kestrel is also a bird (and inherits from the Bird Class), but can fly (unlike the penguin), so it gains the properties of the Flight Class through composition. Similarly, a knight has a sword. It is much more useful and flexible to define different types of swords as classes unto themselves, then place specific swords in the hands of specific knights, rather than have to redefine the sword for each knight who might hold one.
Note that once a class is composited into another class, it will always be acquired by all subclasses through inheritance. So if the Bird class is defined as having flight, all birds will acquire that ability. This is inaccurate, as we’ve discussed above. It will be incumbent upon content authors/administrators to carefully sculpt object hierarchies to avoid such oversights.
The combination of inheritance and composition allows for endless cross-factoring of Classes. Note that all Objects can theoretically be extended or composited, though we may implement a final keyword, which concludes the inheritance chain for classes so finite that they cannot usefully be extended.
The UI for Class creation should be thoughtfully considered for usability and flexibility. Specifically, a user should find a single class from which to extend, and then click an “Extend this Class” button. The new Class will inherit all the properties of the parent, using (by default) the same values. There should also be a drag & drop facility for adding compositional features. There should be a way to identify a “complete” entry from an “incomplete” one (i.e., not all required values are filled in).
Draft architecture for the Wikiup Core Service
As this helps to clarify our approach to implementation, this section describes the intended server-side model and API calls. It should be emphasized, though, that this is only a draft. The actual implementation may be very different.
Class structure
API package
Classes that receive client calls and pass off requests to the rest of the system. Once a request is processed, the results are returned to the client via this same package.
Users package
Responsible for defining and maintaining information on individual users, including activity, roles and ratings.
Entities package
Classes that define Wikiup Classes and the individual entries (‘entities’) within them. Sub-packages here include Classes to define properties, abilities and contracts.
Filters package
A set of Classes with methods designed to facilitate search and retrieval.
Validators package
Utility set responsible for ensuring that data saved into the Wikiup conforms to requirements.
MySQL Package
Layer that sets and retrieves data to/from the DB. These calls are abstracted partially for design clarity, but also to facilitate the possibility of interface with other DBs in future.
API calls
Method: class.create
Purpose: create a new Class in the Wikiup. Note that with all create and update calls, an arbitrary number of properties may be passed to define the entity.
Returns: the class_id of the newly created Class, and the entity_id of the newly created entry, or an error code if the entry failed. Entry may fail due to various transport issues of course, or if the entity doesn’t meet the terms of its specified contract.
Example:
http://api.wikiupgames.com/services/rest/?method=wikiup.entity.create&api_key=XXXXXXXXXXX&user_id=XXXXX&name=Black%20Dragon&contract=XXXXXX&property0=XXXX&propertyValue0=XXX&property1=XXXX&propertyValue1=XXX...
Method: class.createVersion
Purpose: create a new version of an already existing entity. If the optional draft property is set to ‘1’, the new entity version is created, but not available to any user except the creator. This allows a user to create a draft version before officially publishing.
Returns: the entity_id of the new entry. If draft is set to ‘1’, the entity_id returned will be the same as the one sent. Note that in an ideal implementation, the system will search the
Example:
http://api.wikiupgames.com/services/rest/?method=wikiup. class.createVersion&api_key=XXXXXXXXXXX&user_id=XXXXX&class_id=XXXXX&draft=1&name=Black%20Dragon&contract=XXXXXX&property0=XXXX&propertyValue0=XXX&property1=XXXX&propertyValue1=XXX...
Method: class.flag
Purpose: call the administrator’s attention to a Class (usually an indicator of abuse). Note that this indicates that the entire Class is abusive (perhaps a copyright infringement).
Returns: true if the flag was successfully sent.
Example:
http://api.wikiupgames.com/services/rest/?method=wikiup.class.flag&api_key=XXXXXXXXXXX&class_id=XXXXX&user_id=XXXXX&comment_text=Quich%20%brown%20fox
Method: entity.edit
Purpose: edit an existing entity. In general, the Wikiup does not allow this, but exceptions may exist if (1) an entry has been posted as a draft, or (2) an administrator wishes to edit an entry.
Returns: the entity_id of the updated entity.
Example:
http://api.wikiupgames.com/services/rest/?method=wikiup. entity.edit&api_key=XXXXXXXXXXX&user_id=XXXXX&entity_id=XXXXX&draft=1&name=Black%20Dragon&contract=XXXXXX&property0=XXXX&propertyValue0=XXX&property1=XXXX&propertyValue1=XXX...
Method: entity.destroy
Purpose: destroy entity in the Wikiup. Note that in general we don’t allow this in the core service, but the functionality should exist both for the benefit of the deployment kit and for maintenance and abuse prevention.
Returns: true if the entity was successfully destroyed, false if not.
Example:
http://api.wikiupgames.com/services/rest/?method=wikiup.entity.destroy&api_key=XXXXXXXXXXX&user_id=XXXXX&entity_id=XXXXX
Method: entity.fetch
Purpose: retrieve an entity from the Wikiup.
Returns: the data relating to the specified entity_id. We will probably allow for more than one format of data retrieval, but that’s still optional and no parameter for that feature is represented here.
Example:
http://api.wikiupgames.com/services/rest/?method=wikiup.entity.fetch&api_key=XXXXXXXXXXX&entity_id=XXXXX
Method: entity.flag
Purpose: call the admin’s attention to an entity (usually an indicator of abuse). Note that this method calls attention to the entity, rather than the Class as a whole (perhaps someone has entered obscene content).
Returns: true if the flag was successfully sent.
Example:
http://api.wikiupgames.com/services/rest/?method=wikiup.entity.flag&api_key=XXXXXXXXXXX&entity_id=XXXXX&user_id=XXXXX&comment_text=Quich%20%brown%20fox
Method: entity.tagForUse
Purpose: tag an entry as a user’s preferred version. This can be used as part of filtering.
Returns: true if the tag was successfully set.
Example:
http://api.wikiupgames.com/services/rest/?method=wikiup.entity.tagForUse&api_key=XXXXXXXXXXX&entity_id=XXXXX&user_id=XXXXX
Method set: rating
Purpose: set/retrieve ratings for an entity in the Wikiup.
Returns: the averaged rating of the entity being rated. An individual user can only have one rating per entity.
Examples:
http://api.wikiupgames.com/services/rest/?method=wikiup.rating.rate&api_key=XXXXXXXXXXX&user_id=XXXXX&entity_id=XXXXX&rating=X
http://api.wikiupgames.com/services/rest/?method=wikiup.rating.getRating&api_key=XXXXXXXXXXX&user_id=XXXXX&entity_id=XXXXX
Method set: comments
Purpose: add/delete/edit/read comments relating to an entity’s discussion thread.
Examples:
http://api.wikiupgames.com/services/rest/?method=wikiup.comments.addComment&api_key=XXXXXXXXXXX&entity_id=XXXXX&user_id=XXXXX&comment_text=Quick%20brown%fox
http://api.wikiupgames.com/services/rest/?method=wikiup.comments.editComment&api_key=XXXXXXXXXXX&entity_id=XXXXX&user_id=XXXXX&comment_text=Quick%20brown%fox
http://api.wikiupgames.com/services/rest/?method=wikiup.comments.deleteComment&api_key=XXXXXXXXXXX&entity_id=XXXXX&
http://api.wikiupgames.com/services/rest/?method=wikiup.comments.getComments&api_key=XXXXXXXXXXX&entity_id=XXXXX&
Method set: filtering
The filter set is still under consideration. The purpose is to provide the functionality to dynamically arrive at entity versions that meet the requirements of a search (if a user is searching the DB) or a game’s needs (if a client game is dynamic requesting an entity version).
Method set: users
Obvious create/edit methods for managing users and their roles.
Common concerns with the Wikiup model, and solutions
Volatility/Inaccuracy
Problem: Because a Wikiup is constantly changing, an application that relies on it may be rendered unstable. The Wikiup is vulnerable to inaccuracy and deliberate defacement.
Answer: While all the above concerns are true, they don’t take into account the ability of a client to filter based on reputation and determine for itself what content to accept. As long as changes are thoughtfully moderated to avoid bloat (and, if necessary, run through an approval process) clients may be insulated from deliberate or accidental errors.
Also, the Wikiup implementation will forbid incomplete data sets, so no class will appear in the library lacking values for required properties.
Comprehensive Limits
Problem: Different games have different needs. How can one library suffice for all implementations of a game?
Answer: It may well be that we’re never able to accommodate all possible implementations, but contracts allow for our reach to be very, very broad without overwhelming either authors or client games.
Disambiguation of object names
Problem: What if two authors want to define two characters with the same name, but subtly or totally different characteristics? How does the game client tell these apart?
Answer: Classes are not inherently identified by their object name, but by a unique numerical identifier that remains with the Class from its birth. Thus, while it is possible to have two similar characters with identical names (say, two definitions for the beast Grendel), these are unique entities that will be treated separately by the system. There are several ways within the system to disambiguate these Classes. First, it should be the business of the Wikiup system admin and mods to identify duplicate namings and suggest alternate names for clarity. Second, and probably more useful for the game developer, is the Wikiup API’s filter and built-in reputation system. A Wikiup library is ultimately quite vast and arguably not useful in its entirety to any one game client. It is thus incumbent upon the developer to either tag useful Classes herself, or else to rely on the reputation of taggers to point to “better” implementations of ambiguous classes. Every Wikiup API request can carry a filter to find the data that the developer trusts.
Why ‘wikiup’?
The derivation from ‘wiki’ is obvious. In the American West, a wikiup is a plain, single-room dwelling, usually covered in branches (applied to Native American huts). The notion that our Wikiup is something of a plain framework, covered by organic matter, seemed an appropriate metaphor.
It has also been brought to my attention that ‘up’ connects nicely to game concepts such as “power up” or “level up”, and I rather like that.
Why aren’t you using <insert my favorite technology here>?
Simple. I do Flash. I use PHP, XML and MySQL (though I’m considering Ruby for the web service).
So do a lot of other people. Short of handing this over to someone else, I need to
use the technology with which I’m familiar. These technologies are also widely
distributed and commonly understood.