The Virtual Commons

building extensible software for collective action research

vcweb

Web based game engines

Desiderata

  • Open source is preferred to proprietary engines
  • JavaScript / HTML5 based engines is preferred to Flash based engines

JavaScript engines

Flash based game engines

other resources

Creating experiments in vcweb

The intent of the vcweb framework is to provide useful scaffolding and functionality for any kind of web-based experiment. As with most software projects however, its initial design will be tailored to its initial use cases - in our case, the forestry, fishery, and irrigation field experiments as well as a few prototype experiments designed by our other collaborating researchers. We hope to design and implement the software so that it is applicable and useful in broader contexts and welcome any feedback to help us refine and generalize the design and implementation of the framework.

Framework benefits

The vcweb framework is currently implemented in Django and brings all of Django's benefits for web application development including account management, administration pages, data management / object-relational management, and URL/view/template management.


Creating a new experiment


Creating a new experiment in vcweb is done by creating a Django app. In the Django lingo, vcweb is implemented as a project, which is a container for multiple apps. The core of the vcweb framework is implemented as an app and each experiment is also implemented as an app. It is our goal that you can use as many or as little features of the vcweb framework you want by adding only the appropriate dependencies to the core vcweb app within your own custom experiment app. The vcweb app does impose basic namespace conventions on your app. Any actionable URLs within an experiment have to fall under the /experiment-name/... namespace. We may eventually enforce a few URL hooks that need to be implemented as well (e.g., /experiment-name/admin/, /experiment-name/manage, or /experiment-name/start|stop|pause) but the rationale for implementing these should come from the bottom-up as dictated by the community.


User interfaces


The core vcweb app provides some base interfaces and look and feel CSS + Django templates that can be used if you want to get an experiment up and running quickly. You can define your URLs and views and custom templates that extend from these Django templates and customize exactly how you want your experiment interface to look, as well as defining URLs that contain mobile-friendly interfaces and the corresponding JavaScript to differentiate between which version of the web interface should be displayed - this is a simple client-side check that could for example redirect to /experiment-name/mobile/participate if you're using a mobile browser or /experiment-name/participate if you're using a regular browser.


URL management


URLs are chunked off according to a short name given to the experiment and are typically partitioned under /vcweb/experiment-name/whatever - this is completely configurable within the custom experiment app's urls.py. You have complete control over what Python code is executed given a specific URL or if you want to simply forward on directly to a Django template or static HTML page you can also do that within urls.py. See the Django view documentation for more information.


View templates


Django has its own template system which gives you limited programmatic and logical control over how your pages are rendered and variable interpolation. The basic way this works is you visit a URL configured in urls.py and it executes the Python view code registered with that specific URL. The last thing this bit of Python code associated with the URL does is define what template should be rendered as a final result, and what data should be passed to it in the form of a dictionary/map of string variable names bound to data values. These string variable names can then be accessed transparently within your Django template to perform control logic (display data conditionally, iterate over collections, etc.)


Data model


Currently the vcweb core framework offers a full data model that aims to allow for fully flexible experiment data to be collected and managed. This will be outlined more in the vcweb data model page. Basically, configuration and experiment data are stored as key-value pairs using whatever data storage engine Django is currently configured with, typically PostgreSQL or MySQL for production or SQLite for fast development.


Experiments and groups


Each experiment has one or more groups, and each group is comprised of a set of participants. Data for a given experiment is currently collected at the participant level with foreign keys to the combination of the given participant generating the data, the round in which the data was generated, the experiment the data was generated in, the data parameter and value that was generated, and the exact time the data value was stored in the table. The round is the set of configuration metadata associated with a given round in the experiment and contains references to all configuration parameters associated with that specific round including that round's sequence number. Round configuration metadata is currently designed to be unique so if you want to re-use round configuration metadata in multiple experiments we'll need to implement a way to easily copy/clone a round or full experiment's configuration and allow for later tweaking. This is an area that we may decide to refactor at some point in the future.

running vcweb experiments

Experimenter workflow

  1. Create an experiment from the available experiment types (or clone an existing experiment).
  2. Configure the experiment as needed, modifying round durations and other experiment-specific configuration parameters (this won't be implemented until later, but for the time being a select few experimenters can be given access to Django's admin interface)
  3. Add / invite participants to the experiment via mass emails. For controlled experiments in the lab, this can be done transparently via the participant tracker (to be implemented later as well)
  4. Start the experiment when ready, sending all connected participants to an experiment-specific instructions page.
  5. Monitor the experiment and provide explicit input when needed. This will be described in more detail below.

Experimenter driven with timed rounds

We are first implementing support for controlled experiments. These can be experimenter driven at times, with active rounds that have a specific timed duration. Each round has an associated RoundConfiguration that specifies:

  1. whether or not the round should go indefinitely until explicitly signalled by the experimenter (e.g., a checkpoint round).
  2. what type of round it is (current types include quiz rounds, chat rounds, instruction rounds, and normal play rounds.
  3. a integer duration, specified in seconds. If a round has a duration of 0, the round will continue indefinitely until signaled by the experimenter (even if the checkpoint flag is set to false).
  4. an arbitrary number of experiment-specific RoundParameter key-value pairs.
  5. various other book-keeping metadata (creation date, created by, sequence number

Experimenter monitored with long-lived, spaced out rounds

This is to support long-lived experiments that go on over weeks. Each round might be one day or one hour, where participants must contribute to some collective action issue. Will fill in implementation details here later.

Participant workflow

  1. When participants first login to an experiment that hasn't started, they should be ferried to a general instructions welcome screen that acts as a waiting room of sorts.
  2. After the experiment is started by the experimenter, they can progress to the next experiment-specific instructions screen (NOTE: needs server push or constant client polling)
  3. After this, the participant will engage in whatever sequence of round configurations have been specified for the given experiment.

More to come later.

Syndicate content