Alternative directions

If you are setting your game on a ship or spaceship, you may want to use ship style directions, i.e., port and starboard.

There are two ways of doing this. You can either use the built-in library or do it yourself.

Use the built-in library

Add this line to settings.js

settings.libraries.push('shipwise')

Doing it yourself

This will describing how to add shipwise directions simply to illustrate the technique.

We need to set lang.exit_list, which is an array setting the data for each compass direction. This array is used for a few things, such as the buttons on the compass rose and mapping, so has quite a lot of stuff in there, including for the LOOK, WAIT and HELP buttons. There are also the symbols for each direction and the vector data too. Most of it must not be changed.

It needs to go in a file that will be run before you create any locations, but not settings.js; I suggest code.js.

lang.exit_list = [
  {name:'forward-port', abbrev:'FP', niceDir:"forward-port", type:'compass', key:103, x:-1 ,y:1, z:0, opp:'aft-starboard', symbol:'fa-arrow-left', rotate:45}, 
  {name:'forward', abbrev:'F', niceDir:"forward", type:'compass', key:104, x:0 ,y:1, z:0, opp:'aft', symbol:'fa-arrow-up'}, 
  {name:'forward-starboard', abbrev:'FS', niceDir:"forward-starboard", type:'compass', key:105, x:1 ,y:1, z:0, opp:'aft-port', symbol:'fa-arrow-up', rotate:45}, 
  {name:'in', abbrev:'In', alt:'enter|i', niceDir:"inside", type:'inout', opp:'out', symbol:'fa-sign-in-alt'}, 
  {name:'up', abbrev:'U', niceDir:"above", type:'vertical', key:107, x:0 ,y:0, z:1, opp:'down', symbol:'fa-arrow-up'},
  
  {name:'port', abbrev:'P', niceDir:"port", type:'compass', key:100, x:-1 ,y:0, z:0, opp:'starboard', symbol:'fa-arrow-left'}, 
  {name:'Look', abbrev:'Lk', type:'nocmd', key:101, symbol:'fa-eye'}, 
  {name:'starboard', abbrev:'S', niceDir:"starboard", type:'compass', key:102, x:1 ,y:0, z:0, opp:'port', symbol:'fa-arrow-right'}, 
  {name:'out', abbrev:'Out', alt:'exit|o', niceDir:"outside", type:'inout', opp:'in', symbol:'fa-sign-out-alt'}, 
  {name:'down', abbrev:'Dn', alt:'d', niceDir:"below", type:'vertical', key:109, x:0 ,y:0, z:-1, opp:'up', symbol:'fa-arrow-down'}, 

  {name:'aft-port', abbrev:'AF', niceDir:"aft-port", type:'compass', key:97, x:-1 ,y:-1, z:0, opp:'forward-starboard', symbol:'fa-arrow-down', rotate:45}, 
  {name:'aft', abbrev:'A', niceDir:"aft", type:'compass', key:98, x:0 ,y:-1, z:0, opp:'forward', symbol:'fa-arrow-down'}, 
  {name:'aft-starboard', abbrev:'AS', niceDir:"aft-starboard", type:'compass', key:99, x:1 ,y:-1, z:0, opp:'forward-port', symbol:'fa-arrow-right', rotate:45}, 
  {name:'Wait', abbrev:'Z', type:'nocmd', key:110, symbol:'fa-clock'}, 
  {name:'Help', abbrev:'?', type:'nocmd', symbol:'fa-info'}, 
]

As you can see each direction is a dictionary; the important entries in each is the "name", the "abbrev" (abbreviation shown in the compass if you do not use symbols), "niceDir" (how it might be used when describing an NPC going or coming from that way) and "opp" (the name of the opposite direction).

Note that all your exits need to use these new directions, rather than the usual compass directions.

  port:new Exit('hallway'),
  aft:new Exit('cargo_bay'),

Notes

While the file does allow diagonal movement, I am not sure how natural "You can see a door forward-starboard" sounds. You may want to not use diagonals at all.

You might want to include some mechanism to help land-lubbers who do not know port from starboard.

Combining both

The above system, whether using the built-in feature of doing it yourself, changes the entire game, so you can only use shipwise directions. What if you want to swap between them in one game?

Text Only

If you are not using the compass rose, this is fairly straightforward, you just add the extra directions to the data.

const shipwise = [
  {name:'forward', abbrev:'F', niceDir:"forward", type:'compass', key:104, x:0 ,y:1, z:0, opp:'aft', symbol:'fa-arrow-up'}, 
   {name:'port', abbrev:'P', niceDir:"port", type:'compass', key:100, x:-1 ,y:0, z:0, opp:'starboard', symbol:'fa-arrow-left'}, 
  {name:'starboard', abbrev:'ST', niceDir:"starboard", type:'compass', key:102, x:1 ,y:0, z:0, opp:'port', symbol:'fa-arrow-right'}, 
  {name:'aft', abbrev:'A', niceDir:"aft", type:'compass', key:98, x:0 ,y:-1, z:0, opp:'forward', symbol:'fa-arrow-down'}, 
]

for (const el of shipwise) lang.exit_list.push(el)

A complication is the potential for confusion between SOUTH and STARBOARD; I have therefore given STARBOARD the abbreviation ST. Note that the arrow keys on the number pad will only work for compass direction, not shipwise.

Compass rose

If you do have a compass rose, it gets more complicated as we have to flip between the two systems. We will start by replacing what we already have, as we will add a whole new set of fifteen directions, so we can just swap between the two.

const shipwise = [
  {name:'forward-port', abbrev:'FP', niceDir:"forward-port", type:'compass', key:103, x:-1 ,y:1, z:0, opp:'aft-starboard', symbol:'fa-arrow-left', rotate:45}, 
  {name:'forward', abbrev:'F', niceDir:"forward", type:'compass', key:104, x:0 ,y:1, z:0, opp:'aft', symbol:'fa-arrow-up'}, 
  {name:'forward-starboard', abbrev:'FS', niceDir:"forward-starboard", type:'compass', key:105, x:1 ,y:1, z:0, opp:'aft-port', symbol:'fa-arrow-up', rotate:45}, 
  {name:'in', abbrev:'In', alt:'enter|i', niceDir:"inside", type:'inout', opp:'out', symbol:'fa-sign-in-alt'}, 
  {name:'up', abbrev:'U', niceDir:"above", type:'vertical', key:107, x:0 ,y:0, z:1, opp:'down', symbol:'fa-arrow-up'},
  
  {name:'port', abbrev:'P', niceDir:"port", type:'compass', key:100, x:-1 ,y:0, z:0, opp:'starboard', symbol:'fa-arrow-left'}, 
  {name:'Look', abbrev:'Lk', type:'nocmd', key:101, symbol:'fa-eye'}, 
  {name:'starboard', abbrev:'St', niceDir:"starboard", type:'compass', key:102, x:1 ,y:0, z:0, opp:'port', symbol:'fa-arrow-right'}, 
  {name:'out', abbrev:'Out', alt:'exit|o', niceDir:"outside", type:'inout', opp:'in', symbol:'fa-sign-out-alt'}, 
  {name:'down', abbrev:'Dn', alt:'d', niceDir:"below", type:'vertical', key:109, x:0 ,y:0, z:-1, opp:'up', symbol:'fa-arrow-down'}, 

  {name:'aft-port', abbrev:'AF', niceDir:"aft-port", type:'compass', key:97, x:-1 ,y:-1, z:0, opp:'forward-starboard', symbol:'fa-arrow-down', rotate:45}, 
  {name:'aft', abbrev:'A', niceDir:"aft", type:'compass', key:98, x:0 ,y:-1, z:0, opp:'forward', symbol:'fa-arrow-down'}, 
  {name:'aft-starboard', abbrev:'AS', niceDir:"aft-starboard", type:'compass', key:99, x:1 ,y:-1, z:0, opp:'forward-port', symbol:'fa-arrow-right', rotate:45},
  {name:'Wait', abbrev:'Z', type:'nocmd', key:110, symbol:'fa-pause'}, 
  {name:'Help', abbrev:'?', type:'nocmd', symbol:'fa-info'}, 
]


for (const el of shipwise) lang.exit_list.push(el)

Then we need to track which we want, using a "compassGroup" attribute on the player. We need this to change as we move from one zone to another, and the easiest way is to set it in any room the player might arrive in. My example here has a spaceship in the kitchen, so when the player enters the kitchen we set "compassGroup" to "compass" and when the player enters the first room in the spaceship, we set "compassGroup" to "shipwise". It also needs to be set on the player object.

createItem("me", PLAYER(), {
  loc:"lounge",
  regex:/^(me|myself|player)$/,
  examine: "Just a regular guy.",
  hitpoints:100,
  compassGroup:'compass',
})

createRoom("kitchen", {
  desc:"The kitchen is boring... apart from the spaceship, I guess you could go in there.",
  north:new Exit('lounge'),
  in:new Exit('spaceship_aft'),
  beforeEnter:function() { game.player.compassGroup = 'compass' },
})

createRoom("spaceship_aft", {
  desc:"The spaceship is boring, the author really needs to put stuff in it.",
  forward:new Exit('spaceship_forward'),
  starboard:new Exit('kitchen'),
  out:new Exit('kitchen'),
  beforeEnter:function() { game.player.compassGroup = 'shipwise' },
})

I have used in and out to move between the kitchen and spaceship as I think it will be less confusing for the player as she transitions between the systems.

Finally we need to actually change the compass. I am creating a new dictionary here to hold the functions. I can then pass the dictionary to io, which will automatically call the dictionary's "update" function each turn.

const compass = {}

compass.update = function() {
  let s = ''
  for (let i = 0; i < 3; i++) {
    s += '<tr>'
    s += compass.rewriteExit(0 + 5 * i)
    s += compass.rewriteExit(1 + 5 * i)
    s += compass.rewriteExit(2 + 5 * i)
    s += '<td></td>'
    s += compass.rewriteExit(3 + 5 * i)
    s += compass.rewriteExit(4 + 5 * i)
    s += '</tr>'
  }

  $('#compass-table').html(s)

  for (let exit of lang.exit_list) {
    if (game.room.hasExit(exit.name, {excludeScenery:true}) || exit.type === 'nocmd') {
      $('#exit-' + exit.name).show();
    }
    else {
      $('#exit-' + exit.name).hide();
    }
  }
}

compass.rewriteExit = function(n) {
  if (game.player.compassGroup === 'shipwise') n += 15
  let s = ''
  s += '<td class="compass-button" title="' + lang.exit_list[n].name + '">'
  s += '<span class="compass-button" id="exit-' + lang.exit_list[n].name
  s += '" onclick="io.clickExit(\'' + lang.exit_list[n].name + '\')">'
  s += settings.symbolsForCompass ? io.displayIconsCompass(lang.exit_list[n]) : lang.exit_list[n].abbrev
  s += '</span></td>'
  return s
}

io.modulesToUpdate.push(compass)

The "update" function builds all the HTML to be inserted into the compass element, using "rewriteExit", pretty much as is done in _io.js. The trick is in the first line of "rewriteExit"; if we want shipwise directions, we add 15 to skip past the standard directions. If the function is passed 1, that would be "north", but if we add 15 - the number of entries in the standard directions dictionary - that takes us to "forward".

Arrow keys

To get the arrow keys to work right, we can add a settings.customKeyResponses which will fire before any other keycodes are captured. This will return true if we are handling the key press and false otherwise.

settings.customKeyResponses = function(keycode) {
  const slice = lang.exit_list.slice(game.player.compassGroup === 'shipwise' ? 15 : 0)
  const dir = slice.find(el => el.key === keycode)
  if (!dir) return false
  
  const location = w[game.player.loc]
  io.msgInputText(dir.name)
  $('#textbox').val('')
  parser.parse(dir.name)
  return true
}

The second line of the function looks for the first entry it can find with the right keycode. The trick here is in the line before, which takes a slice of the array of exit directions; if we are looking at shipwise directions, that slice omits the first 15 entries corresponding to the normal compass directions.

If no keycode is found, we return false; this is not a direction, we are not interested so let something else deal with it.

If the keycode is found, we record the command, and clear the text input, pass the direction to the parser to handle, and return true to stop anything else trying to use the keycode.