Monthly Archives: April 2013

Developing a Serious Game Application – Part 1


Development of the serious game application has hit a roadblock due to problems in creating a valid Model representation of a text-only wiki article that are preventing the Makahiki database from being initialized. Once this problem is fixed, being able to perform standard Django database operations on the Articles should allow other standard pseudo-wiki-like features like article searches or revision management to be implemented to some degree.

False Starts: django-wiki

In my previous post on this project, I had been considering trying to incorporate modules from benjaoming’s django-wiki project into Makahiki. The problem with this approach is that it would essentially amount to taking an existing, full-fledged web application with its own authentication system and trying to link this system to Makahiki’s user database. At best, Makahiki would end up serving as a glorified login screen, with its widgets needing to pull from the external wiki database and integrate this with Makahiki’s database. While the django-wiki package appears to be a useful Django add-on, it did not seem as if it lent itself well to gamified integration with Makahiki in the limited development time I had.

The Article Model

The Article model, in its present, incomplete state, does not actually create an article that the user can edit. Rather, it stores metadata about the article – title, which editors can work on it, etc. – in the database. Since it seems impractical to store a hypothetical article (possibly with embedded images in a future iteration of the project) as a text field in a database, the goal is eventually to store a link to the actual article file as a field of the Article model. The database could then be queried to retrieve all revisions of the article (revision number is another field), and links to the article as generated by Django would point to the latest version. At present, Makahiki’s script cannot initialize the database because the error TypeError: __init__() got an unexpected keyword argument ‘required’ is preventing the Article model from being validated, so it is likely that an attempt to upload the application to Heroku in its present state would also fail. Oddly enough, the script worked once and produced this error only after I navigated to the Profile page; on the second use of, the script failed to complete its run and displayed the same error.

A TypeError.

The database was able to initialize once with the Article model, but this error appeared on the Profile page. The next use of failed to initialize the database completely, with the same error.

Implementing New Models

The practice of creating and being able to revise an article is very different from what Makahiki is currently designed to do: it is equipped to measure and reward user-generated actions and content, but naturally it is not possible for users to substantially alter the site. Now that I have a better understanding of the work that needs to be done to incorporate articles into the database, the greatest potential problem is the likelihood that most of the work over the remaining two weeks will need to go towards back-end, pseudo-wiki-implementing code, rather than into making Makahiki’s Smart Grid Game able to measure and reward training scenarios and user contributions within the wiki.

Future Objectives

In the short term, the goal is to fix the current version of the Article model such that the Article model will validate, and to then upload the application to Heroku. The next goal is to make the Article model or the article_mgr manager able to maintain references to the latest version of an article and provide a link to an editable version of the article, which will use the Markdown language that Makahiki already supports. A subsequent goal would be to modify one or more SmartGrid challenges to detect that a user has created a certain number of unique articles and/or revisions, and create a badge for it; alternately, I might attempt to incorporate a ratings module as well. Once the Article model is functional, building widgets to do basic database lookups for searches by title or author or loading a list of all revisions to an article should be relatively trivial. Articles are likely to be limited to text only for the foreseeable future, as support for image and file uploads is a lower priority given the current issues with the Article model and the feasibility of its gamification.

UPDATE: Heroku Application

My compilation and initialization failure was the result of extra commas in the file. Once these were removed, the database could be initialized normally.

A draft version of the create_article widget.

The form does not have line breaks between fields, resulting in form help text seeming as if it is associated with the field below it instead of the field above it.

As mentioned, the changes at this point are minimal: the article creation form is displayed on the Profile page, and it redirects to an error page instead of a confirmation page or an editing page if the Submit button is clicked. Furthermore, it is not currently possible for any user, admin or non-admin, to delete the entry the Submit button creates in the database.

While trying to set up player0 as a dummy user, I was unable to continue the setup dialog beyond the point shown below. I can only conclude that my database model changes somehow broke other aspects of the setup process.

Now I cannot set up new users. Clicking on the right button to continue does nothing.

Now I cannot set up new users. Clicking on the right button to continue does nothing.


Developing for Makahiki – Part 1

Task 1: Hello World

This weeks’ class exercise in developing new widgets for Makahiki began as everything does in software engineering: with "Hello World.”" This tutorial breaks down the process of designing a new widget for Makahiki into a few basic steps:

  1. Initialize the new widget
  2. Edit its file to determine what output it will return
  3. Edit its templates/index.html; this is the page section to display the values returned by its file
  4. Add the widget to the list of widgets in Makahiki’s file
  5. In Makahiki’s challenge design configuration menus, add the new widget to a page
  6. Add a help topic for the widget
  7. Add the widget to fixtures/base_pages.json and fixtures/base_help.json to make it permanent (optional)
  8. Push changes to Github or Heroku as applicable.

I finished this without problems and got hello_world working locally.

The hello_world demo widget.

Above: The hello_world demo widget running locally.

The hello_world widget by itself, however, does not do much. The next set of tasks, after modifying score_mgr to support collecting data on user groups, involved adding more widgets to support data collection from player groups, which do not come with Makahiki by default.

Task 2: Add Group Widgets

Update score_mgr to Support Groups

My initial approach was one in which I attempted to add group support to score_mgr by creating new versions of its team data functions by replacing references to “team” with references to “group.” This was based on the assumption, based on, that a Group could be accessed as a field of a Team (which is itself a field of a user_profile). This assumption was partially correct; the problem lay in the way I was processing the dictionary value returned from the widget’s file, which was itself accessing profile__team__group__name to get the list of all groups.

Create a Group Scoreboard Widget

It was in attempting to create the group_scoreboard widget that I discovered that I was attempting to access the group value incorrectly. Initially, I thought that the error messages I experienced were due either to problems in the new functions I had added to start_mgr or the use of the admin account’s profile when the admin account was not linked to a group. Instead it was the result of another standard computer science problem, accessing a variable which did not exist.

A Django field error.

This problem turned out to be caused by a mistaken attempt to check for profile__team__group__isnull. “group” is not a property of profile__team.

As it turned out, the NoneType errors were caused by my file. Originally, it returned the dictionary of group scores as follows:

return group_score

The code block Django uses to return named parameters is actually:

return {
    "group_score": group_score

which I had altered for some reason. Without this, would always return null when Django processed index.html and attempted to access “group_score.”

There was another problem after this in which the widget displayed correctly but showed the text “last” and “points” instead of actual team names. The group_points_leaders function I created in score_mgr, modified from team_points_leader, has this block of code:

entries = ScoreboardEntry.objects.filter(
    round_name = round_name, profile__team__isnull=False).values(
    last=Max("last_awarded_submission")).order_by("-points", "-last")

The entries variable is initialized to a dictionary and passed to I knew the problem was probably in my Django loop code in index.html, which tried to process the dictionary by looping through keys and values. The better way of accessing the dictionary in this case is to access individual, named parameters from each dictionary element:

{% for f in view_objects.group_scoreboard.group_score %}
   <!-- Some HTML formatting eliminated for clarity -->
   <td>{{ f.profile__team__group__name }}</td>
   <td>{{ f.points }}</td>
{% endfor %}

The group_scoreboard widget, showing the test group.

This section updated April 8, 2013.

Create a Group Resource Widget

I will update this section if I complete it.

Create a Group Prize Widget

I will update this section if I complete it.

Create Two Group Statistics Widgets

I will update this section if I complete it.

Suggestions for Makahiki Documentation Improvement

It is hard to say in this case if my problems are due to any issues in the Makahiki documentation, as they could just as easily result from my fixating on trying to salvage an unusable method of extending start_mgr to support groups. As far as I know, no one else had any problems with this step, so I am inclined to attribute my problems to configuration or coding errors on my end rather than problems with the documentation. Nevertheless, adding a type hierarchy diagram (manually created or automatically generated) to the documentation might be helpful. Though the widget system and user/group/team system is conceptually simple, it was not very clear to me which types had access to which other types.

This post will be updated if the score_mgr problems are resolved.

Makahiki Administration and Gamification, Version 3

Issues To Address

After reviewing the latest plan for my application, my professor pointed out a few areas of the design that might require further thought. The goal of my application was to provide a potentially wiki-like means for users to create guides, combined with a Stack Overflow-like means of awarding reputation and pointing out issues for future work.

The problem with this kind of system is that it is mostly disconnected from whatever documentation the developers produce – it may not keep up with software updates or newly discovered bugs, and at best it serves as a kind of patch on flaws in the developer documentation. As my professor pointed out, unless the authors are careful to mention specific details about their guide (what OS it applies to, what version of the software it’s meant to use, et cetera) it is difficult for a new user to know if a guide is applicable, and even more difficult to know if it will work. A reputation system may or may not be helpful here; it is only as good as the number of site users who bother to rate an article, and if they do not leave comments, it is not clear which parts of the article were useful or need to be fixed.

The challenge, then, is to design a system in which users are more closely connected to the production of developer documentation. It is probably not good to go “full wiki,” as the developers should still retain some control over the direction of development and the style and organization of documentation. Furthermore, the work of wiki administration and maintenance would probably require diverting personnel from actual development tasks, which would be a problem for smaller teams. This is more of an administrative issue, though, and in principle it could be taken care of by eventually nominating administrators from the user community to enforce a Wikipedia-like manual of style. Teaching this manual of style to new users is in and of itself a problem, since it might become a new barrier to entry.

The New Workflow

The revised workflow.

Above: The revised, wiki-based workflow.

The Makahiki system already contains features for recording when users have completed certain activities and for unlocking higher tiers of activities in response. The badge system is, from a game design standpoint, easy to think of as a reward system for wiki contributions, some awarded automatically and some by the decision of administrators. (For something similar, see Wikipedia’s Barnstars.) In this system, Makahiki’s Smart Grid Game would be re-purposed for a wiki training game, in which a user plays around in a sandbox and unlocks basic user privileges as he or she goes, earning badges as a certification of basic training. Just as Wikipedia regularly selects featured articles, the authors of the highest-rated guides in each category could periodically be invited to contribute to the documentation of new builds of a software system by the developers.

I think there is also a need for an “Issue” article type, for users who have found a problem and have documented it but do not know how to fix it. Instead of just a usual bug-tracking system, which users may be unaware of, and in which it can be difficult to figure out at first glance why an issue has a certain severity rating, articles on the issues themselves could become collection points for comments, and eventually become troubleshooting guides.

In this system, articles could be segregated by project or by general category. Hypothetically, developers (as administrators) could manage the creation of article categories and the registration of new projects with the site. Links to the current versions of official documentation could be provided on the project’s page, and users could contribute to multiple projects.

On the Surface: Minor UI Tweaks

User pages, version 2.

Above: A slight redesign of the user page.

I have decided to call the more generally targeted version of the site “SetupBooster,” for reasons which in large part have to do with the lack of unused domain names related to speed and launch metaphors. (Things like and Kickstarter were reserved long ago.) It is probable that SetupBooster is already taken, but I will worry about less fundamental issues like site name and logo after the site itself is up and running. The slight redesign adds more mentions of user achievements and article ratings, and eliminates the newsfeed (which was essentially a duplicate of the newsfeed on the main page).

Since Issues is going to be an article type, the system for reporting problems with articles is being renamed to “bugs.” Both have similar meanings, but I am not sure which name would be more or less confusing for each. The article categorization system is probably just going to be an identifying string without any article format restrictions, as I can’t think of a specific format to write an issue report in that would differ substantially from an article – both would be required to include software version and operating system, and would feature a general description of some aspect of the software. This allows additional types of articles – suggestions for future development, or in the context of Makahiki, popular community-designed widgets with good setup documentation for creating them – to be added to the system more easily. A manual of style could be created for each type, but that is probably something best left to human administrators to enforce.

In One Month

In one month, I will attempt to integrate an open-source wiki application and a ratings module into Django and see if Makahiki’s Smart Grid Game can be configured to detect changes to versions of an article. Though the django-wikiapp and django-ratings look promising at first glance, I do not know what will be involved in integrating them with each other and the Makahiki badges system. At a minimum, it is my hope that, by the end of this semester, test users will be able to create a new user, run through a series of training games in their own article sandbox which reward them with badges, create and edit their own test articles, and rate their quality. Depending on how similar the wiki application is to Wikipedia, I may not need to implement a separate commenting system if the wiki application provides Talk pages. The short-term goal of this project is to create a ratings-driven Wikipedia-like system that runs on Django, uses the Smart Grid Game to train users, and possibly awards badges based on a running count of how often the user has done certain editing tasks.