Creating a Javascript game tutorial

Question

I have a Facebook game titled Rails Across Europe. It is written in PHP/MySQL/Facebook Javascript. One of the big features that is lacking in my game is an interactive user tutorial. I have a screencast, but I don't think it's helpful enough. I've noticed that most users who start a game only play one or two turns before giving up. It's a complicated game and it would greatly benefit from an interactive tutorial.

The problem is that I have no clue as to how to create a tutorial like this. The game consists of a map of europe containing european cities, rail lines (e.g. track), and goods supplied by the cities. The player is supposed to build track to connect cities, navigate his trainn along the track, pick up goods in one city, and deliver them to another city which has a demand for the goods, whereupon he will get paid.

The game contains many different event handlers for things like building track, moving the train, loading and unloading cargo at cities, among other things.

I'm struggling with how to structure this tutorial so it stays in synch with the user's actions (and vice-versa) and how to determine if the user has taken the correct action that would permit the tutorial to move on to the next step and how to know what the next step is.

Here are samples of my front-end js code:

var openCargoHolds = 0;
var cargoHoldsUsed = 0;
var loadCargoDialog = null;
var isIE = false;
function setBrowserIsIE(value) {
  isIE = value;
}
function moveTrainAuto() {
//debugger;
//consoleTime('moveTrainAuto');
consoleLog('moveTrainAuto');
  var ajax = new Ajax();
  ajax.responseType = Ajax.JSON;
//consoleTime('moveTrainAuto::move-trains-auto');
  ajax.ondone = function(data) {
//consoleTimeEnd('moveTrainAuto::move-trains-auto');
//consoleTimeEnd('moveTrainAuto::get-track-data');
//debugger;
    var trackColor = (data.route_owned) ? '#FF0' : '#888';
    var trains = [];
    trains[0] = data.train;
    removeTrain(trains);
    drawTrack(data.y1, data.x1, data.y2, data.x2, trackColor, trains);
//debugger;
    if(data.code == 'UNLOAD_CARGO') {
consoleLog('moveTrainAuto::unloadCargo');
      //unloadCargo();
      //myEventMoveTrainManual(null); //continue moving train until final destination is reached
      moveTrainManual();
    } else if (data.code == 'MOVE_TRAIN_AUTO') { // || data.code == 'TURN_END') {
      moveTrainAuto();
    } else if (data.code == 'TURN_END') {
consoleLog('moveTrainAuto::turnEnd');
      turnEnd();
    } else {
      /* handle error */
    }
  }
  ajax.post(baseURL + '/turn/move-train-auto-track-data');
//consoleTimeEnd('moveTrainAuto');
}
function moveTrainAutoEvent(evt) {
//debugger;
  //moveTrainAuto();
  //myEventMoveTrainManual(null, false);
  moveTrainManual();
}
function moveTrainManual() {
//consoleTime('moveTrainManual');
consoleLog('moveTrainManual');
//debugger;
  state = MOVE_TRAIN_MANUAL;
  var ajax = new Ajax();
  ajax.responseType = Ajax.JSON;

  if(!trainInTransit) {
    var actionPrompt = document.getElementById('action-prompt');
    actionPrompt.setInnerXHTML('<span><div id="action-text">'+
      'Move Train: Select destination'+
      '</div>'+
      '<div id="action-end">'+
      '<form method="POST">'+
      '<input type="button" value="Replace Demands" id="replace-demands-btn" style="width: 130px;" />'+
      '<input type="button" value="Upgrade Train" disabled="disabled" id="upgrade-train-btn" class="btn" />'+
      '<input type="button" value="Build Track" id="build-track-btn" class="btn" />'+
      '<input type="button" value="Manage Cargo" id="manage-cargo-btn" class="btn" />'+
      '</form>'+
      '</div></span>');
    var actionButton = document.getElementById('build-track-btn');
    actionButton.addEventListener('click', moveTrainEventHandler);
    actionButton = document.getElementById('replace-demands-btn');
    actionButton.addEventListener('click', moveTrainEventHandler);
    actionButton = document.getElementById('upgrade-train-btn');
    actionButton.addEventListener('click', moveTrainEventHandler);
    var loadCargoButton = document.getElementById('manage-cargo-btn');
    loadCargoButton.addEventListener('click', moveTrainEventHandler);
  } else {
    var actionPrompt = document.getElementById('action-prompt');
    actionPrompt.setInnerXHTML('<span><div id="action-text">'+
      'Train in-transit to final destination...</div></span>');
  }
  ajax.ondone = function(data) {
consoleLog('ajax.moveTrainManual');
    if(data.code == 'TURN_END') {
consoleLog('moveTrainManual::turnEnd');
      turnEnd();
    } else {
//debugger;
      //myEventMoveTrainManual(null);
    }
  }
  ajax.post(baseURL + '/turn/move-train-manual');
//consoleTimeEnd('moveTrainManual');
}
function unloadCargo() {
//debugger;
consoleLog('unloadCargo');
  var actionPrompt = document.getElementById('action-prompt');
  actionPrompt.setTextValue('Unloading cargo...');
  var ajax = new Ajax();
  ajax.responseType = Ajax.JSON;
  ajax.ondone = function(data) {
//debugger;
    if(data.unloadableCargo.length == 0) {
consoleLog('unloadableCargo == 0');
      moveTrainManual();
      //loadCargo();
    } else {
consoleLog('unloadable cargo='+dump(data.unloadableCargo));
      var i = 0;
      var j = 0;
      var ucCount = data.unloadableCargo.length;
      for(i = 0; i < ucCount; i++) {
        var cargoDialog = new Dialog();
        cargoDialog.showChoice('Unload Cargo', 'Unload  ' + data.unloadableCargo[i].goods_name + ' at ' + data.unloadableCargo[i].city_name + ' for ' + data.unloadableCargo[i].payoff + 'M euros?');
        cargoDialog.iVal = i;
        cargoDialog.onconfirm = function() {
//consoleLog('iVal='+this.iVal);
//consoleLog('unloadable cargo onconfirm='+dump(data.unloadableCargo));
          var ajax = new Ajax();
          ajax.responseType = Ajax.JSON;
          var param = {"city_id": data.unloadableCargo[this.iVal].city_id, "goods_id": data.unloadableCargo[this.iVal].goods_id, "payoff": data.unloadableCargo[this.iVal].payoff};
          ajax.ondone = function(demandData) {
            refreshDemands();
            // update balance
            setHtmlBalance(demandData.balance);
            if(demandData.post_to_wall) {
              Facebook.streamPublish('', demandData.attachment, demandData.action_links);
            }

            ajax.responseType = Ajax.JSON;
          //debugger;
            ajax.ondone = function(data) {
              if(!data.already_won && data.funds >= data.winning_balance) {
                var dialog = new Dialog().showMessage('Congratulations!', 'You have earned over '+data.winning_balance+'M euros. You have won! You may continue playing or start a new game.');
                dialog.onconfirm = function() {
                  moveTrainManual();
                }
              }
              moveTrainManual();
            }
            ajax.post(baseURL + '/turn/get-player-stats');
          }
          ajax.post(baseURL + "/turn/do-unload-cargo", param);
        }
        cargoDialog.oncancel = function() { moveTrainManual(); }
      }
    }
  }
  ajax.onerror = function() {
    var dialog = new Dialog().showMessage('Request taking too long', 'The system is taking too long to process this request. Please try refreshing the page. If this does not work, please Contact Us with a description of your problem. We are sorry for the inconvenience.');
  }
  ajax.post(baseURL + '/turn/unload-cargo');
}
function loadCargo() {
//consoleLog('Entering loadCargo()');
  var actionPrompt = document.getElementById('action-prompt');
  actionPrompt.setTextValue('Loading cargo...');
  var ajax = new Ajax();
  ajax.responseType = Ajax.JSON;
  ajax.ondone = function(data) {
//consoleLog('Entering ondone for load-cargo');
//debugger;
    ajax.responseType = Ajax.FBML;
    ajax.ondone = function(fbjsData) {
//consoleLog('Entering ondone for load-cargo-dialog-fbjs');
//debugger;
      if(data.loadableCargo.length == 0) {
//consoleLog('Calling moveTrainManual()');
        moveTrainManual();
      } else {
//consoleLog('Instantiating loadCargoDialog');
        if(loadCargoDialog == null) {
          loadCargoDialog = new Dialog();
          //if browser is IE, move dialog up 50px to compensate for bug that causes it to shift down the screen
          if(isIE) {
            //loadCargoDialog.setStyle('position', 'relative');
            //loadCargoDialog.setStyle('top', '-50px');
          }
          loadCargoDialog.showChoice('Load Cargo', fbjsData, 'Minimize', 'Pass');
        } else {
          if(isIE) {
            //loadCargoDialog.setStyle('position', 'relative');
            //loadCargoDialog.setStyle('top', '-50px');
          }
          loadCargoDialog.showChoice('Load Cargo', fbjsData, 'Minimize', 'Pass');
        }
        var dlgPrefixString = document.getElementById('dlg-prefix-string').getValue();
        //var dlgPrefixString = dlgPrefixElem.getValue();
//consoleLog('Setting dlgBtnNew');
        var dlgBtnNew = document.getElementById(dlgPrefixString+'-load-new-submit');
        dlgBtnNew.cityId = data.loadableCargo.city_id;
        dlgBtnNew.trainId = data.loadableCargo.train_id;
        dlgBtnNew.prefixString = dlgPrefixString;
        dlgBtnNew.loadCargoDialog = loadCargoDialog;
        dlgBtnNew.addEventListener('click', cargoEventHandler); //loadNewCargo);
//consoleLog('Setting dlgBtnDiscard');
        var dlgBtnDiscard = document.getElementById(dlgPrefixString+'-discard-existing-submit');
        dlgBtnDiscard.cityId = data.loadableCargo.city_id;
        dlgBtnDiscard.trainId = data.loadableCargo.train_id;
        dlgBtnDiscard.prefixString = dlgPrefixString;
        dlgBtnDiscard.loadCargoDialog = loadCargoDialog;
        dlgBtnDiscard.addEventListener('click', discardExistingCargo);
        loadCargoDialog.onconfirm = function() {
//consoleLog('Entering loadCargoDialog.onconfirm');
          // Submit the form if it exists, then hide the dialog.
          loadCargoDialog.hide();
          actionPrompt = document.getElementById('action-prompt');
          actionPrompt.setInnerXHTML('<span><div id="action-text">'+
            'The "Load cargo" dialog has been minimized'+
            '</div>'+
            '<div id="action-end">'+
            '<form action="" method="POST">'+
            '<input type="button" value="Maximize" id="next-phase" onclick="loadCargo();" />'+
            '</form>'+
            '</div></span>');
          actionButton = document.getElementById('next-phase');
          actionButton.setValue('Maximize');
          actionButton.addEventListener('click', loadCargoEventHandler);
//consoleLog('Exiting loadCargoDialog.onconfirm');
        };
        loadCargoDialog.oncancel = function() {
//consoleLog('Entering loadCargoDialog.oncancel');
          moveTrainManual();
//consoleLog('Exiting loadCargoDialog.oncancel');
        }
      }
//consoleLog('Exiting ondone for load-cargo-dialog-fbjs');
    }
    ajax.onerror = function() {
      var dialog = new Dialog().showMessage('Request taking too long', 'The system is taking too long to process this request. Please try refreshing the page. If this does not work, please Contact Us with a description of your problem. We are sorry for the inconvenience.');
    }
    ajax.post(baseURL + '/turn/load-cargo-dialog-fbjs', data);
//consoleLog('Exiting ondone for load-cargo');
  }
  ajax.onerror = function() {
    var dialog = new Dialog().showMessage('Request taking too long', 'The system is taking too long to process this request. Please try refreshing the page. If this does not work, please Contact Us with a description of your problem. We are sorry for the inconvenience.');
  }
  ajax.post(baseURL + '/turn/load-cargo');
//consoleLog('Exiting loadCargo');
}
function loadCargoEventHandler(evt) {
  if(evt.type == 'click') {
    loadCargo();
  }
}
function trackEventHandler(evt) {
  var x1 = evt.target.x1;
  var x2 = evt.target.x2;
  var y1 = evt.target.y1;
  var y2 = evt.target.y2;
  var cost = evt.target.cost;
  var prefixString = evt.target.prefixString;

  evt.target.payDialog.hide();

  ajax = new Ajax();
  ajax.responseType = Ajax.JSON;

  switch(evt.target.getId()) {
    case prefixString + '-confirm-pay-submit':
      ajax.ondone = function() {
        var empty = [];
        drawTrack(parseInt(y1), parseInt(x1), parseInt(y2), parseInt(x2), '#FF0', empty);
//new Dialog().showMessage('test', 'balance='+balance);
        balance = balance - parseInt(cost);
        setHtmlBalance(balance);
        saveCityStartElem.setSrc(publicURL + '/images/city_marker.gif');
        saveCityStartElem = null;
        var actionPrompt = document.getElementById('action-prompt');
        var innerHtml = '<span><div id="action-text">Build Track: Select a city where track building should begin</div>'+
                        '<div id="action-end">'+
                        '<form action="">'+
                        '<input type="button" value="End Track Building" id="next-phase" onClick="moveTrainAuto()" />'+
                        '</form>'+
                        '</div></span>';
        actionPrompt.setInnerXHTML(innerHtml);
        var btn = document.getElementById('next-phase');
        btn.addEventListener('click', moveTrainAutoEvent);
        state = TRACK_CITY_START;
      }
      ajax.onerror = function() {
        new Dialog().showMessage('Track Building Error', 'An error occured while building this track. Please try again.');
      }
      ajax.post(baseURL + '/turn/build-track-confirmed', {"europass_used": 0});
      break;

    case prefixString + '-cancel-pay-submit':
      saveCityStartElem.setSrc(publicURL + '/images/city_marker.gif');
      saveCityStartElem = null;
      var actionPrompt = document.getElementById('action-prompt');
      var innerHtml = '<span><div id="action-text">Build Track: Select a city where track building should begin</div>'+
                      '<div id="action-end">'+
                      '<form action="">'+
                      '<input type="button" value="End Track Building" id="next-phase" onClick="moveTrainAuto()" />'+
                      '</form>'+
                      '</div></span>';
      actionPrompt.setInnerXHTML(innerHtml);
      var btn = document.getElementById('next-phase');
      btn.addEventListener('click', moveTrainAutoEvent);
      state = TRACK_CITY_START;
      ajax.post(baseURL + '/turn/build-track-resume');
      break;

    case prefixString + '-europass-pay-submit':
      ajax.ondone = function() {
        var empty = [];
        drawTrack(parseInt(y1), parseInt(x1), parseInt(y2), parseInt(x2), '#FF0', empty);
//new Dialog().showMessage('test', 'balance='+balance);
        saveCityStartElem.setSrc(publicURL + '/images/city_marker.gif');
        saveCityStartElem = null;
        var actionPrompt = document.getElementById('action-prompt');
        var innerHtml = '<span><div id="action-text">Build Track: Select a city where track building should begin</div>'+
                        '<div id="action-end">'+
                        '<form action="">'+
                        '<input type="button" value="End Track Building" id="next-phase" onClick="moveTrainAuto()" />'+
                        '</form>'+
                        '</div></span>';
        actionPrompt.setInnerXHTML(innerHtml);
        var btn = document.getElementById('next-phase');
        btn.addEventListener('click', moveTrainAutoEvent);
        state = TRACK_CITY_START;
      }
      ajax.onerror = function() {
        new Dialog().showMessage('Track Building Error', 'An error occured while building this track. Please try again.');
      }
      ajax.post(baseURL + '/turn/build-track-confirmed', {"europass_used": 1});
      break;
  }
}
function cargoEventHandler(evt) {
  //new Dialog().showMessage('loadNewCargo', 'city id='+cityId+', train id='+trainId);
//debugger;
  var cityId = evt.target.cityId;
  var trainId = evt.target.trainId;
  var prefixString = evt.target.prefixString;

  evt.target.loadCargoDialog.hide();

  switch(evt.target.getId()) {
    case prefixString + '-load-new-submit':
//debugger;
      ajax = new Ajax();
      ajax.responseType = Ajax.JSON;
      param = { 'load-cargo-submit': "Load new goods", 'city-id': cityId, 'train-id': trainId };
      ajax.ondone = function(data) {
        openCargoHolds = data.openCargoHolds;
        cargoHoldsUsed = 0;
        ajax.responseType = Ajax.FBML;
        param = { 'openCargoHolds': data.openCargoHolds, 'cityGoods': data.cityGoods, 'trainId': data.trainId };
        ajax.ondone = function(fbjsData) {
    //debugger;
          var dialog = new Dialog().showChoice('Load Cargo', fbjsData, 'Load cargo', 'Cancel');
          var numGoods = data.cityGoods.length;
          for(var i = 1; i <= numGoods; i++) {
            var decrementGoodsArrow = document.getElementById('goods-decrement-' + i);
            decrementGoodsArrow.addEventListener('click', goodsAdjustmentHandler);
            var incrementGoodsArrow = document.getElementById('goods-increment-' + i);
            incrementGoodsArrow.addEventListener('click', goodsAdjustmentHandler);
          }
          dialog.onconfirm = function() {
//debugger;
            var goods = [];
            var goodsIds = [];
            numGoods = document.getElementById('goods-count').getValue();
            for(var i = 0; i < numGoods; i++) {
              j = i + 1;
              goods[i] = document.getElementById('goods-' + j).getValue();
              goodsIds[i] = document.getElementById('goods-id-' + j).getValue();
            }
            var trainId = document.getElementById('train-id').getValue();
            param = { "goods": goods, "goods-id": goodsIds, "train-id": trainId };
            ajax.responseType = Ajax.JSON;
            ajax.ondone = function(data) {
              loadCargo();
            }
            ajax.onerror = function() {
              var dialog = new Dialog().showMessage('Request taking too long', 'The system is taking too long to process this request. Please try refreshing the page. If this does not work, please Contact Us with a description of your problem. We are sorry for the inconvenience.');
            }
            ajax.post(baseURL + '/turn/do-load-cargo-new', param);
            //dialog.hide();
          };
          dialog.oncancel = function() {
            loadCargo();
          }
        }
        ajax.post(baseURL + '/turn/load-cargo-new-dialog-fbjs', param);
      }
      ajax.post(baseURL + '/turn/load-cargo-select', param);
      break;
    case prefixString + '-discard-existing-submit':
      ajax = new Ajax();
      ajax.responseType = Ajax.JSON;
      param = { 'load-cargo-submit': "Discard existing goods", 'city-id': cityId, 'train-id': trainId };
      ajax.ondone = function(data) {
        ajax.responseType = Ajax.FBML;
        param = { 'openCargoHolds': data.openCargoHolds, 'trainGoods': data.trainGoods, 'trainId': data.trainId };
        ajax.ondone = function(fbjsData) {
          var dialog = new Dialog().showChoice('Discard Cargo', fbjsData, 'Discard cargo', 'Cancel');
          dialog.onconfirm = function() {
//debugger;
            var goods = [];
            var goodsIds = [];
            numGoods = document.getElementById('goods-count').getValue();
            for(var i = 0; i < numGoods; i++) {
              j = i + 1;
              goods[i] = document.getElementById('goods-' + j).getValue();
              goodsIds[i] = document.getElementById('goods-id-' + j).getValue();
            }
            var trainId = document.getElementById('train-id').getValue();
            param = { "goods": goods, "goods-id": goodsIds, "train-id": trainId };
            ajax.responseType = Ajax.JSON;
            ajax.ondone = function(data) {
              loadCargo();
            }
            ajax.post(baseURL + '/turn/do-load-cargo-discard', param);
            //dialog.hide();
          };
          dialog.oncancel = function() {
            loadCargo();
          }
        }
        ajax.post(baseURL + '/turn/load-cargo-discard-dialog-fbjs', param);
      }
      ajax.post(baseURL + '/turn/load-cargo-select', param);
      break;
  }
  return true;
}

Answer 1

It would take a while for anyone to understand your code, so I think it's a bit hard to provide exact code examples for your specific case, but for some general ideas...

Each step in the tutorial could for example have a set of requirements. Click this button, do this action. So to know when the user has done something, you'd need to add event listeners on those actions and have them change the state of the current "step".

Once your step's requirements have been met, it would simply get replaced by the next step. At this point, the event handlers and such would be updated to track on the new step's requirements.

For example, let's say you'd have a step where the user must build a track from A to B, and then run a train through it. In a case like this, you could have requirements that a train must go to A, and afterwards, to B. So your game should have some sort of an event on the train reaching a specified station, and you would track this event.

Hope this helps.