Space Nerds In Space - A Multi-player Starship Bridge Simulator

S P A C E   N E R D S   I N   S P A C E

An Open Source Multi-player Starship Bridge Simulator for Linux

Captain your starship through adventures with your friends


SOURCE
CODE

SCREEN
SHOTS

DISCUSSION
FORUM

DEV
VIDEOS

DEV
DISCUSSION

REDDIT
FORUM


Please consider donating to support development of Space Nerds In Space. Patreon

Or consider contributing code, either to the core codebase, or mission scripts. Or, if you have crypto-money burning crypto-holes in your crypto-wallets, maybe buy some SNIS related crypto-art

This site is a member of the geekring! Check some other geeky websites here: Previous site -- Next site

Some video of game play at HackRVA in Richmond, VA, 2016-02-16


Space Nerds In Space is an open source (GPLv2) cooperative multiplayer starship simulator for linux (may also work on Mac). So go out and get together with a crew of your linux-nerd friends and their computers in a room with a projector or TV, and go forth and explore the galaxy.

One computer runs the central server simulation of the game's universe. Each player's computer acts as a station on a simulated spaceship. There are stations for Navigation, Weapons, Engineering, Communications, Damage Control, and the "Main View", an out-the-window 3d rendering. Multiple starships each with their own team may connect to the server for bridge-vs-bridge combat, or for cooperative play. Additionally, a game master may inject and control various NPC ships into the game to entertain the players, and scenarios may be constructed with a Lua based scripting API.

You might be reminded of Artemis Spaceship Bridge Simulator, and you would not be out of line, as this game was the inspiration for Space Nerds In Space. Within a month after mentioning Space Nerds In Space publicly, and before I'd gotten very far at all, but about the time I realized that what I was working on might be more than vapor, I wrote to Thom Roberts, expressing my desire to write a linux based spaceship bridge simulator with essentially the same raison d'etra as Artemis (though differing radically in the details), and he replied:

I can think of no greater flattery, especially since I've seen other games that made ME want to make my own version. Good luck!

And so I proceeded.

If you're on mobile, you would probably have a better time viewing this site on a real computer.


Contents


Latest development video (November 2018):

Here is a short mini-documentary created at the premier hackerspace of Houston, TX, TX/RX Labs, camera work and editing by Jack Younger. This is from 2013, and the graphics and other aspects of the game are much better now, but this video will still give you a good idea of what the game is all about.

Space Nerds In Space was designed with hackerspaces in mind -- where else are you going to find enough people to run a linux-based multi-player LAN game spaceship simulator for Star Trek nerds but a hackerspace? The very first 3D model created for Space Nerds In Space may seem strikingly familiar. If you're a member of a hackerspace, this game is explicitly made for you.


Here are a few screen shots:

A Rocky Planet

Image of a rocky planet

A Terrestrial Planet

Image of a terrestrial planet

A Gas Giant

Image of a gas giant

More Screen Shots


Build Instructions

Here's a quick preview of the build instructions detailed below:

  1. Acquire necessary hardware (some linux machines, network switch, cables, projector, stereo, etc.)
  2. Clone git repository or obtain source tarball and unpack it.
  3. Install dependencies (run util/install_dependencies on apt-based systems)
  4. Build the code (type "make")
  5. Download additional art assets (type "make update-assets")
  6. Run the game (type "./snis_launcher")

(Here is a long, boring video demonstrating how to install)

Step 0: Acquire Hardware and OS

This is a linux game. You will need a computer running linux that has a reasonably decent GPU. A Raspberry Pi 4 (with 4Gb RAM) and heatsinks is sufficiently powerful to run the game at 720p for some screens, namely NAVIGATION, ENGINEERING, DAMAGE CONTROL, SCIENCE and COMMS, but is not really good enough for the MAIN VIEW, WEAPONS, or DEMON screens (you'll see very low FPS). Here is a long boring youtube video demonstrating installation and running SNIS on a Raspberry Pi 4B if you want to see for yourself what it's like. Older Raspberry Pis are generally not powerful enough to run the game.

It is possible to run the game entirely on a single linux laptop, but for the full and proper spaceship experience you will want six linux computers, a network switch, a projector or large TV, and a stereo system for audio in a reasonably dark room.

The game is currently developed using Mint 17.3 It is within the realm of possibility that the game could be made to build and work on Mac OSX (it has been done before, but not since 2014 or so.) You're on your own if you want to try to run it on Mac, and my understanding is that newer Macs don't support OpenGL, which means you're out of luck.

Step 1: Download the Source Code

The source code is here: Space Nerds In Space github page

NOTE: Do NOT perform these steps as root!

To get the source code, there are three methods:

  • If you are a registered github user, type (as a non-root user):
    git clone git@github.com:smcameron/space-nerds-in-space.git
  • If not a registered github user, you can still use git with https. Type (as a non-root user):
    git clone https://github.com/smcameron/space-nerds-in-space.git
  • Finally, you can just download a snapshot zipfile without using git at all:

    After downloading the zip file, you must unpack the zip file. Type (as a non-root user):

    unzip space-nerds-in-space-master.zip cd space-nerds-in-space-master

Step 2: Install Dependencies

There is a script, util/install_dependencies. In theory it can install dependencies on apt, yum, zypper, or rpm based systems, but it has only been tried with apt based systems. If you want to see what it will do without actually doing anything, it has a --dry-run option.

util/install_dependencies
If you don't want to run this script, or find that it does not work for you, you can install the dependencies manually, as described below. If util/install_dependencies performs its job satisfactorily, you can advance to Step 3.
sudo apt-get install build-essential; sudo apt-get install portaudio19-dev; sudo apt-get install libpng-dev; sudo apt-get install libvorbis-dev; sudo apt-get install libsdl2-dev; sudo apt-get install libsdl2-2.0-0; sudo apt-get install liblua5.2-dev; sudo apt-get install libglew-dev; sudo apt-get install libttspico-utils; # optional, for text to speech sudo apt-get install sox; # for "play" command, used by text to speech # (The following are optional) sudo apt-get install espeak; # optional alternative to libttspico-utils sudo apt-get install alsa-utils; # optional alternative to sox, for "aplay" command sudo apt-get install openscad; # optional, only needed if you intend to work on 3D models. # Also, it is recommended to get it from http://www.openscad.org/downloads.html # as the version in the repos tends to be out of date. sudo apt-get install git; # Version control, useful if you're hacking on the game sudo apt-get install stgit; # Useful for making patches if you're hacking on the game. It's like "quilt" but on top of git.

If you want to try the optional pocketsphinx based local speech recognition, you will want the following packages:

sudo apt-get install pocketsphinx-utils; sudo apt-get install pocketsphinx-lm-en-hub4; sudo apt-get install pocketsphinx-lm-en-hub4; sudo apt-get install libpocketsphinx1;

The above list may be incomplete, and these are the package names on mint 17.3 / ubuntu, so may be different on RPM based systems.

NOTE: Later, the Makefile will download the Opus library source ( https://archive.mozilla.org/pub/opus/opus-1.3.1.tar.gz). This library is used for the voice chat feature. If you intend to build on a machine which does not have internet access, or for whatever reason do not want the makefile to download this library at build time, you can download it yourself beforehand. Or you can modify the Makefile and change "WITHVOICECHAT=yes" at the top of the file to "WITHVOICECHAT=no" and it will not download this library (and you won't have the voice chat feature.)

NOTE: problems building on SuSE Leap 15.1. The following problems/solutions have been conveyed to me regarding SuSE Leap 15.1. This information is not very complete or accurate, but it is the best I have for now. Please feel free to send me improvements to these instructions. See Bug 222.

  1. Need to install pkg-config and pkg-config_files.
  2. Need to set pkg-config-path environment variable
  3. All references to lua 5.2 in the Makefile need to be changed to lua 5.3. Note, we only compiled snis_client (via "make bin/snis_client") which shouldn't need lua at all. I don't know if the differences between lua 5.3 and lua 5.2 are significant enough to break things. I normally use lua 5.2 on my systems. Changes to Lua 5.3 -- at a quick glance I didn't see anything that I think will be problematic.

Step 3: Build the Code

To build the code, make sure you are in the top level directory for the game ("space-nerds-in-space" if you got the source using git, or "space-nerds-in-space-master" if you downloaded the zip file), and type (as a non-root user):

make

You should see quite a lot of output, like this:

COMPILE mathutils.c COMPILE snis_alloc.c COMPILE snis_socket_io.c ... many steps omitted here ... LINK bin/snis_server LINK bin/snis_client LINK bin/snis_limited_client LINK bin/snis_multiverse

If you have problems building the code, it likely means there is some missing dependency. Double check that you have all the required dependencies installed.

You can also file a bug report if you think you have discovered a problem with the build process, or the instructions here. I believe you will need a github account to file a bug report.

Step 4: build openscad models (optional, not recommended)

Or you can skip to step 5 and just download the models instead (recommended). This step will take a long time and requires that you installed OpenSCAD. In general, unless you are working on the models, you can and should skip this step. (Again, as a non-root user):

make models

Step 5: Download additional assets

If you skipped step 4 and didn't build the openscad models, they will be downloaded in this step, along with some other things. This step requires an internet connection. If you performed step 4, you may skip this step though it is not recommended, as you will be missing some additional solarsystem assets. As a non-root user:

make update-assets

Step 6. Run the Game on a single system (Try this before trying multiplayer)

Type (as a non-root user):

    $ ./snis_launcher 

         Welcome to Space Nerds In Space

    ------------------------------------------------------------
    No SNIS processes are currently running.
    ------------------------------------------------------------

       1. Launch SNIS lobby server
	    The lobby server allows clients to find servers
	    There should be one lobby server total.
       2. Launch SNIS multiverse server
	    The multiverse server stores player ship data
	    There should be one multiverse server total
       3. Launch SNIS server
	    There should be one snis server per solarsystem.
	    There should be at least one instance of snis_server.
       4. Launch SNIS client process
	    There should be one snis client process per player
	    plus one more per ship for the main screen.
       5. Launch limited SNIS client process (no Open GL required).
       6. Stop all SNIS processes
       7. Stop all SNIS clients
       8. Stop all SNIS servers
       9. Check for asset updates
       10. Enter Lobby Host IP addr (currently localhost)
       0. Quit
       Choose [0-10]: _

Choose option 1, then option 2, then option 3, then option 4 (taking defaults for any questions you might be asked.)

After awhile, you should see a screen that looks something like this:

Image of a typical network setup

  1. Click on the MAIN SCREEN ROLE checkbox to be sure it is checked.
  2. The very first time you run it, leave the CREATE SHIP box checked. On subsequent runs, make sure CREATE SHIP is not checked.
  3. Enter the name of your ship in the "SHIP NAME" field.
  4. Choose a password for your ship and enter it in the PASSWORD field. (Note: the passwords are not cryptographically secure.)
  5. Click the "ENTER LOBBY ..." button in the lower left part of the screen

Once connected to the lobby, you should see something like this:

Image of the lobby screen

Click on the white text "KARADO". When you do that, you should see:

Click on the "CONNECT TO SERVER" button on the right side of the screen. After you do that, you should briefly see this:

and then this should quickly be replaced be an "out the window" view of space, as below, the "main screen" view of Space Nerds In Space. It may not look exactly like this as your ship will be placed in a semi-random location facing an arbitrary direction. If you've gotten this far, congratulations, you're doing better than most.

Image of out the window view

Step 6. Play around

Keyboard Controls

The function keys are used to switch between screens, except for F1, which is the 'help' key.

  • F1 is the help screen. What it displays depends on which screen you're on.
  • F2 - NAVIGATION
  • F3 - WEAPONS
  • F4 - ENGINEERING
  • F5 - DAMAGE CONTROL
  • F6 - SCIENCE
  • F7 - COMMUNICATIONS
  • F8 - MAIN SCREEN
  • F9 - DEMON SCREEN (dungeon master screen)

To quit the game, press ESC and confirm using arrow keys and ENTER. Note, this only quits your client process. You can re-join the server (via "./snis_launcher" script option 4) It still leaves several processes running, the snis_server, the lobby process and snis_multiverse. To kill all of them, run the "./killem" script.

NAVIGATION SCREEN

From the navigation screen, you can steer the ship and maneuver around. Here is a 10 minute tutorial video about the Navigation screen.

Note: Initially, your ship may have power to all systems turned off via Engineering. Many things won't work without power, including steering and moving the ship. See the section on Engineering, below.

Navigation Controls

You can use the following keys to steer the ship:

           Q   W   E                ^
                                    |
           A   S   D          <-        ->
                                    |
                                    V
  • A and D, and Left Arrow and Right Arrow will yaw the ship left and right, respectively.
  • W and S, and Up Arrow and Down Arrow will pitch the ship down (forward) and up (back), respectively. (If you want to invert these, press Ctrl-I).
  • The backquote key controls the position of the camera in the 3D view, moving it closer or farther from the ship. Press it multiple times to cycle through several possible camera positions.
  • + and - (plus and minus) and the mouse scroll wheel control the camera zoom level.
  • The vertical slider control on the upper right hand side of the screen is the ship's throttle. Use this to control how fast the ship moves.
  • The R button above the throttle slider toggles the ship into or out of reverse thrusting.
  • The horizontal slider control below the warp drive controls how much power the warp drive uses. To use the warp drive, set the warp drive control slider to the desired level, wait until the warp drive gauge reaches the desired value, and press the ENGAGE WARP button. Set the warp drive power to zero when not in use to conserve power, although doing so will make warping your way out of trouble take longer, so bear that in mind.
  • The GREEN ARROW on the screen points in the direction of whatever entity the SCIENCE OFFICER has selected for scanning. A good way to navigate is for the SCIENCE OFFICER to scan whatever you wish to navigate towards (e.g. a distant planet) and then the NAVIGATION OFFICER can follow the GREEN ARROW
  • The CYAN ARROW indicates which direction the weapons are currently pointed. Note that the weapons are mounted on top of the ship, and cannot fire on anything beneath the plane parallel to the floor of the ship. Keep this in mind while battling other ships. You need to make sure your guns are able to face the enemy, and you need to be aware that driving the ship in an erratic manner makes it very difficult for the WEAPONS OFFICER to hit his targets. The WEAPONS OFFICER will remind you if you forget.
  • To dock at a star base:
    • Have the COMMS OFFICER hail the station and request permission to dock. To receive permission to dock, you must be reasonably close to the station, and your shields must be lowered.
    • Press the DOCKING MAGNETS button to engage the docking system. (to disengage the docking system press it again.)
    • Maneuver the ship towards one of the docking ports on the station. When close enough, your ship will latch on.
    • To disconnect from the station, press the DOCKING MAGNETS button again.
  • Use the STANDARD ORBIT button when near a planet to enter "standard orbit".
  • The COMPUTER button allows you to ask the computer to do something. You can control most aspects of the ship in this way. For example, you can type in "navigate to the nearest starbase", and it should point your ship in the direction of the nearest starbase.

WEAPONS SCREEN

From the weapons screen, you can fire the laser turret and launch torpedoes. Here is a short tutorial video about the Weapons screen.

The weapons screen

Weapons Screen Controls

  • The mouse controls where the guns are pointed. The guns can yaw left and right and pitch up and down, but cannot roll.
  • When the mouse is at the bottom center of the screen, the guns will be pointed straight ahead.
  • Moving the mouse from the bottom to the top of the screen moves the guns through the full range of pitch.
  • Moving the mouse to the left side of the screen to the right side of the screen moves the guns through the full range of yaw. (Note: Using the arrow keys, you can also yaw and pitch the guns. With the arrow keys, the yaw range is not limited (guns can rotate 360 degrees. This discrepancy could be considered a bug.)
  • The Left mouse button and the SPACE BAR fire the phasers.
  • The Right mouse button and the Z key fire torpedoes.
  • The mouse scroll wheel or the + and - (plus and minus) keys control the WAVE LENGTH of the phasers. The SCIENCE OFFICER can use the ships scanners to determine what is what the most effective value for the wave length is for a given enemy.
  • The CHARGE graph shows how much power will be released in the next phaser shot. It takes some time for the phasers to recharge. Firing rapidly means each shot contains less energy and does less damage (but if you miss, you will have wasted less energy.) If the phasers are damaged, or ENGINEERING has diverted power from the phasers, it may take longer to recharge.

ENGINEERING SCREEN

From the engineering screen, you can control how power and coolant is distributed to the various systems of the ship. Here is a tutorial video about the Engineering and Damage control screens.

The engineering screen

Engineering Screen Controls

  • Along the left side of the screen are the power and coolant distribution controls for each of the systems on the ship,
    • SHIELDS
    • PHASERS
    • COMMS
    • SENSORS
    • IMPULSE DRIVE
    • WARP DRIVE
    • MANEUVERING
    • TRACTOR BEAM
  • The slider controls labeled PWR control how much power is available for a given system. This is not quite the same as how much power the system actually uses. Most systems will automatically use as much power as you give them. Some systems (e.g. SHIELDS and WARP DRIVE have additional controls controlling how much power they actually use (e.g. the controls on the Navigation screen control how much power the warp drive will use.) You can think of these power controls on the left side of the engineering screen as a power deprivation system. You're really placing limits on how much power the systems have access to, not telling them how much power to use.
  • Note that as you deprive power from some systems, more total power is available to distribute among the other systems, so you may have to adjust other systems power and coolant levels to keep things from overheating.
  • The slider controls labelled COOLANT control how much coolant each system gets. If a system is using too much power relative to how much coolant it gets, it will overheat and start damaging itself.
  • The charts on the right side of the screen show the STATUS and TEMPERATURE of each system. If a system is too hot, the TEMPERATURE graph will flash red, and this means the system is damaging itself.
  • The STATUS bar shows the general health of each system. Hovering over the STATUS bar with the mouse will show a popup window that gives the status of each of the components of that system broken out. The components may be repaired on the DAMAGE CONTROL screen.
  • There are two buttons on the screen labeled 1 and 2. These are presets for setting many power and coolant controls at once. The 1 preset button sets the controls with most systems powered up, but with the warp drive powered down and the tractor beam powered down. This setting is useful for just driving around. The 2 preset button turns all systems off.
  • The DAMAGE CONTROL button switches to the DAMAGE CONTROL screen.
  • The SHEILDS slider control in the upper right part of the screen controls the amount of energy the shields use. The higher the value, the more effective the shields will be. Set to maximum, the shields will use all the power available to them (which might be zero, if the SHIELD PWR control is depriving the shields of power.)

DAMAGE CONTROL SCREEN

From the damage control screen, you can repair the various systems of the ship. Take a look at the tutorial video for the Engineering and Damage control screens above.

The damage control screen

Damage Control Controls

  • Use the Arrow Keys or W, A, S, D keys to control the movement of the robot.
  • Use the Space Bar to control the robot's gripper.
  • The screen shows each of the systems on the ship, with each system having three components. The components may become damaged, making the systems less effective.
  • To repair a component, maneuver the robot near the component and use the gripper to pick up the component. If the component is not too badly damaged, the robot will repair it right there. After the component is repaired, operate the gripper to put the component back.
  • Note, you must put components back in the correct slots for them to work correctly, otherwise the systems will not operate well.
  • If a component is too badly damaged, you will need to take the component to the repair station located at the bottom. Put the component into one of the slots on the repair station and wait a moment for it to repair. You can pick it up before it is fully repaired and repair it to completion on the way back to replace the component in its slot in the appropriate system.
  • If you do not have enough players, or if you simply do not want to manually repair the ship, you can press the AUTO button, and the robot will autonomously repair the ship by itself. It probably won't do it as quickly as you could do it manually though.

SCIENCE SCREEN

From the science screen, you can scan ships, planets, asteroids, launch the mining robot and help navigate to distant targets.

The science screen

Short Range Scanner

Science Short Range Scanner Controls

  • The Mouse Scroll Wheel or the RANGE slider control at the top of the screen controls the range (distance) of the short range scanner.
  • The Left and Right Arrow keys or the A and D keys control the direction the scanning beam is pointed. The boundaries of the scanning beam is indicated by two flickering lines on the display.
  • The Up and Down Arrow keys or the W and S keys control the scanning beam width. The wider the beam is the more volume it covers, but the less resolution it has. The narrower the beam is, the less volume it covers, but the more resolving power it has.
  • Items in the scanner are displayed at a distance from the center which corresponds to the 3D distance.
  • When the scanner has resolved an entity, you can click on it with the mouse, and it, and nearby resolved entities will "pop up" out of the display to give you an idea of how they are situated in 3D space.

The science screen

Scanning Target Details

Science Details Screen

  • Once an entity is resolved by the scanner and selected, you can press the DETAILS button to see more details about the selected item. What you see depends on the type of the item.
  • The Warp Factor value gives you an idea of what value to use if you wish to travel to the entity via the warp drive (that is, you may want to relay this information to the NAVIGATION OFFICER.)
  • If the entity is a ship, the SHIELD PROFILE may indicate that some phaser frequency might be especially effective (so you may want to relay this information to theWEAPONS OFFICER.)

The details view of the science screen

Long Range Scanner

Science Long Range Scanner Controls

The long range scanner is useful for locating distant planets and starbases. It shows a 3D view of the space around your ship.

  • The Mouse Scroll Wheel or the RANGE slider control at the top of the screen controls the range (distance) of the long range scanner.
  • The Left and Right Arrow keys or the A and D keys control the direction the scanning beam is pointed. The boundaries of the scanning beam is indicated by two orange dotted lines on the display forming a kind of "orange slice".
  • The Up and Down Arrow keys or the W and S keys control the scanning beam width. The wider the beam is the more volume it covers, but the less resolution it has. The narrower the beam is, the less volume it covers, but the more resolving power it has.
  • The comma, and forward slash keys rotate (yaw) the scanned volume sphere to the left or right, respectively.
  • The period and L keys rotate (pitch) the scanned volume sphere down and up, respectively.
  • The K and semicolon keys rotate (roll) the scanned volume sphere counter-clockwise and and clockwise, respectively.
  • The ALIGN TO SHIP button aligns the view with the ship so that the view is as if from behind the ship with the ship facing forwards and up is up, left is left, right is right, etc.

COMMUNICATIONS SCREEN

From the communications screen, you can hail starbases and other player ships and control what is displayed on the "main screen" as well as activate the RED ALERT alarm. You also control the ship's inventory and can interact with the ship's computer to ask it questions or even use it to control almost any aspect of the ship.

The communications screen

The row of buttons at the top is for the COMMS OFFICER to control what is displayed on the MAIN SCREEN. For this to work best, individual player stations should not have the MAIN SCREEN ROLE checked (on the NETWORK SETUP SCREEN when they joined the game) but only the computer attached to the projector or big TV should have the MAIN SCREEN role checked. Essentially these buttons make all terminals that have the MAIN SCREEN role switch to displaying the selected station instead. The idea behind this comes from Captain Picard's command, "On screen!" The captain can command any station's screen be displayed "On Screen!" and the COMMS OFFICER can "make it so". Note: it is also possible for any player to press Ctrl-O on their station to make their screen be displayed on the main screen. If they press Ctrl-O a second time, the main screen reverts to showing the main view out the window into space. So if the captain orders "Weapons, On Screen!", either the Weapons Officer can press Ctrl-O, or the Comms Officer can press the WEAPONS button on the COMMS screen. Again, if players have the "MAIN SCREEN" role checked when they join the game, it can be a bit confusing, because then their own computer will be considered to be a "main screen". In general, there normally should only be one computer per bridge that joins the game with the MAIN SCREEN role enabled, and that computer should be the one connected to a projector.

The "EMF" chart in the upper right shows a measuring of local EMF. When an NPC ship scans the players ship, this chart will show elevated levels of EMF. This can give a heads up that some ship is scanning you, and an attack might be coming soon.

The MAIN SCREEN button in the lower right portion of the screen makes the last 4 lines received appear on the main screen so everyone can see them.

The RED ALERT button toggles the red alert system on and off.

The shields display is there so the COMMS officer can know if a request to dock will be denied due to shields still being up.

The zoom slider control at the bottom of the screen controls the zoom level of the MAIN SCREEN

So what can Comms do with this terminal interface? First of all, anything which is typed in that is not a command is broadcast on the current channel, which is by default channel 0, which all player ships receive. You can also switch channels, and only player ships tuned to the particular channel will receive those messages. The intent here is for player-to-player chat in a multi-bridge setup. The channel system is also used (implicitly) for communications with starbases and with mining bots.

Commands you can type in are preceded with a slash, '/', along the lines of IRC commands.

    /help -- displays a list of commands (I need to update the help screen)
    /computer ",
    /channel channel-number - change current channel",
    /eject cargo-bay-number - eject cargo",
    /hail ship-name - hail ship or starbase on current channel",
    /inventory - report inventory of ship's cargo hold",
    /passengers - report list of passengers
    /about - report information about the game (i.e. version number, etc.)

Of the above, /hail, and /computer are the most powerful.

/hail is how you communicate with starbases to request permission to dock, or other things that starbases do (not all of which are implemented yet):

    LOCAL TRAVEL ADVISORY
    REQUEST PERMISSION TO DOCK
    BUY WARP-GATE TICKETS
    REQUEST REMOTE FUEL DELIVERY
    BUY FUEL
    REPAIRS AND MAINTENANCE
        BUY SHIELD SYSTEM PARTS
        IMPULSE DRIVE PARTS
        BUY WARP DRIVE PARTS
        BUY MANEUVERING PARTS
        BUY PHASER BANKS PARTS
        BUY SENSORS PARTS
        BUY COMMUNICATIONS PARTS
        BUY TRACTOR BEAM PARTS
    ARRANGE TRANSPORT CONTRACTS
        BUY CARGO
        SELL CARGO
        BOARD PASSENGERS
        DISEMBARK PASSENGERS
        EJECT PASSENGERS
    SIGN OFF

You may /hail other player ships, or mining bots. The mining bots have some functionality accessed via comms:

    STATUS REPORT
    RETURN TO SHIP
    TRANSPORT ORES TO CARGO BAYS
    STOW MINING BOT
    RETARGET MINING BOT
    SIGN OFF

If you aren't sure of the name of the mining bot, you can ask the SCIENCE OFFICER to scan it.

The /computer command is the most powerful action the Comms officer can use, with this, the entire ship may be controlled just by asking the computer to do things in English. For example, stuff like this should all work:

    /computer set a course for the nearest starbase
    /computer launch the mining bot
    /computer lower shields
    /computer set warp power to 100%
    /computer engage warp drive
    /computer turn left 10 degrees
    /computer engineering on screen
    /computer calculate a course to the nearest asteroid
    /computer describe 
    /computer set warp drive coolant to 50 percent

MAIN SCREEN

The main view

From the main screen, you can steer the ship with the ARROW KEYS and with the A, W, S, D keys and additionally Q and E allow you to roll the ship. The primary purpose of the main screen view it to be projected on a large screen for all players to view at once.

The backquote key cycles through first person and a few third person views of the ship.

The + and - (plus and minus) keys and the Mouse Scroll Wheel zoom and unzoom the camera. Additionally the zoom can be controlled from the COMMS screen.

SHIFT-W toggles the main screen view between front facing and weapons facing. This is fun to let the whole crew see what the WEAPONS OFFICER is busy destroying.

Note, in a proper multi-player setup, the MAIN SCREEN ROLE (on the NETWORK SETUP SCREEN, see below) should not be active (checked) for most players, but only for the computer which is connected to the projector or big TV.

The R key can be used to cycle through different renderer modes (this is really just for debugging though.)

DEMON SCREEN

From the demon screen, the game master can inject all kinds of objects into the game, direct NPC ships, run Lua scripts and construct scenarios to entertain the other players. Note: The "demon" screen began life as a debugging screen, and it contains kind of a mish-mash of features that don't necessarily hang together in a very coherent way. Consider yourself warned. Some quirkiness lies ahead.

The demon screen

Game Master Screen (aka "Demon" screen).

  • General Controls:
    • On the 2D screen
      • Selecting objects is done with the RIGHT MOUSE BUTTON. To deselect an object, click it again with the RIGHT MOUSE BUTTON. or use the SELECT NONE button on the left side of the screen. You can also drag with the right mouse button to select a rectangular area. Objects in this rectangular area that were already selected will be deselected, and those which were not previously selected will be selected.
      • Moving objects is done by dragging with the middle mouse button.
      • Zooming is done with the Mouse Scroll Wheel. Where you zoom in is determined by the mouse pointer location.
      • When one of the object buttons on the left side of the screen is active (e.g. SHIP, PLANET, ASTEROID, STARBASE, NEBULA, MONSTER), then the RIGHT MOUSE BUTTON places an object of that type instead of selecting objects.
    • On the 3D screen
      • Navigate around by right clicking on objects. You will fly in near those objects.
      • Turn left, right, or pitch up and down by right clicking on empty space. Clicking closer to the bottom edge of the screen pitches down, the top edge pitches up, the left edge yaws left, the right edge yaws right. The closer to the center of the screen the slower the yaw or pitch, the closer to the edge of the screen the faster the the yaw or pitch.
      • Select objects with the middle mouse button -- they will blink pink when selected.
      • De-select objects by clicking the middle mouse button on them again. The will stop blinking pink.
      • Move objects by first selecting them, then flying to where you want them to be, then click the MOVE button on the left side of the screen.
      • Use the HOME button on the left side of the screen if you get lost.
  • The HOME button returns the camera (2D or 3D) to a fixed location (e.g. if you get lost zooming around).
  • The SHIP button
    • On the 2D screen this is a toggle. When it is active you can then click with the right mouse button to place ships into the universe. The type of ship is random. With the 2D view, you only control 2 axes of the placement, the 3rd axis is selected randomly but limited to a relatively thin slice. Though the slice is relatively thin, in absolute terms it is quite thick, so it is not really possible to place things precisely.
    • On the 3D view, when you click the ship button, a ship is emitted immediately right where you are. The type of ship is random.
  • The STARBASE, PLANET, ASTEROID, NEBULA, and MONSTER buttons behave just like the SHIP button except they emit objects of the appropriate type rather than ships. NOTE: MONSTER currently doesn't work.
  • The CAPTAIN allows the game master to "captain" an NPC ship -- that is, drive it around and shoot with it. This is best done in the 3D view. To "captain" an NPC ship, select it in the 3D view with the middle mouse button -- it should turn MAGENTA and start blinking. Then press the CAPTAIN button. You can now steer the ship with the arrow keys and fire the torpedoes with the TORPEDO button. To stop captaining an NPC ship, deselect it with the middle mouse button.
  • The DELETE deletes the selected objects.
  • The SELECT NONE button de-selects any objects which are currently selected.
  • The TORPEDO only works when CAPTAINING an NPC ship. It fires a torpedo from the NPC ship.
  • The PHASER button currently does nothing.
  • The 2D/3D button toggles between 2D and 3D view.
  • The MOVE button (3D view only) moves the selected objects to your current location.
  • The EXAG SCALE checkbox makes objects appear bigger than they really are so that you can see them from greater distances.
  • The NET STATS checkbox shows some graphs about network statistics. Currently there are graphs showing:
    • Total bytes/sec transmitted from the snis_server process to all clients
    • Total bytes/sec transmitted from all clients to the snis_server process
    • Round trip latency in milliseconds between this client and the snis_server process.
    The EXECUTE button executes whatever command is typed into the text box immediately above it. Commands are as follows:
    • help - displays a short summary of commands.
    • mark - (2D view only) On the 2D view, if you right click, a flashing blue plus will appear in the display. You can mark the location with a name, by typing, for example: "mark orion". Then later you can use the word "orion" to refer to this location. (This command isn't terribly useful.)
    • name - give the currently selected group of objects a name. For example, you might select a group of ships and type "name myfleet" to give them collectively the name "myfleet".
    • attack - commands one group to attack another. The groups must be previously named with the "name" command. For example, you might type "attack myfleet theirfleet" to command your fleet ("myfleet") to attack their fleet ("theirfleet").
    • goto - command a named group to travel to a marked destination. For example, you might type "goto myfleet orion".
    • patrol - not implemented
    • halt - not implemented
    • identify - identify a previously named group by deselecting all objects and then selecting the named object.
    • say - cause the currently captained NPC ship to transmit something on channel 0. For example "say make like a tree and get outta here".
    • clear all - Deletes all objects except for player ships.
    • aidebug - Turns on some debug information about NPC ship AI state.
    • safemode - toggles "safemode". In "safemode", if a player ship runs out of fuel, it will be magically refueled, and NPC ships won't attack the player (if they are already attacking when safemode is entered, they won't immediately stop though.) There is no indicator whether safe mode is active. The purpose of this is to make testing easier (i.e. testing things out without danger of getting killed.)
    • enscript - saves the current state of objects to a Lua script so that they may be restored. Not everything is saved, but most things are. This is useful if you want to use the demon screen to populate a universe for a scenario and then store that setup in a Lua script. For this to work the snis_server process must have been started with the --enable-enscript option. The lua script is created on the server in share/snis/luascripts. Example: enscript myscript.lua
    • TTS - Text to speech. Select one or more player ships, then use the tts command to cause the computer on those ships to speak something. (This appears to be broken at the moment.)
    • CONSOLE - toggle the demon screen console on and off. The console is a large terminal-like text box that you can interact with.
    • VARS [regexp] - list tweakable variables and their minimum, maximum, and default values on the demon console. There are a number of tweakable variables that can affect gameplay. You may optionally also specify a regular expression as an argument to the VARS command to restrict the output to only those commands whose name or description matches the regular expression.
    • SET variable = value - set a tweakable variable. The special value DEFAULT sets the variable back to its default value. List the tweakable variables using the VARS command.
    • CLIENTS - list the connected clients. The currently displayed station for the client is listed, along with the client number, the client ship, and the possible client roles (as a bitfield. See the ROLE command, below.)
    • ROLE client-number role-modification - Modify or list the permissible roles for a specified client number. The client numbers may be obtained using the CLIENTS command (see above.)

      Possible roles are as follows:

      • MAIN VIEW
      • NAVIGATION
      • WEAPONS
      • ENGINEERING
      • DAMAGE CONTROL
      • COMMS
      • SCIENCE
      • DEMON
      • TTS (text to speech)
      • SOUND SERVER
      The command takes several forms. Here are some examples:
      ROLE 10 lists the roles for client number 10.
      ROLE 7 MAINrestrict client number 7 to role MAIN SCREEN.
      ROLE 7 +ENGadd ENGINEERING role to client 7
      ROLE 4 -WEAPremove WEAPONS role from client 4.
      ROLE 3 ALLallow client 3 to use all roles.
      NOTE: You only have to type the first three characters of the role names (e.g. ENG is the same as ENGINEERING.)
      NOTE: it is not possible to remove the DEMON role from a client.
    • LOCKROLES - Lock all clients to their current roles. This is useful if you want players to select their own roles initially, and then confine them to those roles for the whole game or a period of time. If a client is on the MAINSCREEN, or the DEMON screen, then this will have no effect on that client. ENGINEERING and DAMAGE CONTROL are considered a single screen for purposes of this command.
    • UNLOCKROLES - Allow all clients to freely switch between all roles. This is the complement of the LOCKROLES command.
    • ROTATEROLES - Rotate roles on client stations. Used in conjuction with LOCKROLES, this is a good way to keep people from hogging the weapons console.
    • FIND - find an object with the given name, e.g. "find enterprise" will find any objects or player ships named "enterprise" and print out the object IDs for any matching objects.
    • DUMP and CDUMP - print out the state of the specified object ID. "Dump" prints out the state on the server, "Cdump" prints out the state on the client. The server and the client don't necessarily have the same (or any) information for all fields. This command is really a debugging aid for developers.
    • AITRACE - trace (continuously print) the AI state of the specified object id. If no object id is specified, any current tracing activity is ceased.
    • FOLLOW - Causes the 3D demon screen camera to follow the specified object ID. If no object ID is specified, any current following activity is ceased. Note that the "HOME" button will not work if an object is currently being followed.
    • LUA - run a lua script. The lua scripts must reside on the server in share/snis/luascripts. Currently there are few scripts:
      • MAINMENU.LUA
      • DEMOLISHER.LUA
      • SAVING-PLANET-ERPH.LUA
      • SILLY-SPACE-BATTLE.LUA
      • SPACEPOX.LUA
      • TRAINING-MISSION-1.LUA
      • TRAINING-MISSION-2.LUA

      Example: saving-planet-erph

      Note: Now if you enter a command that isn't a built-in, an attempt is made to run it as a lua script. This means that instead of entering lua saving-planet-erph.lua, you can just enter saving-planet-erph, which is a little more convenient.


Multiplayer Setup

Typical multiplayer network setup

What a typical multiplayer setup looks like, showing which processes typically run on which physical machines.

Step 0. Obtain Necessary Hardware for Multiplayer Setup

You will need the following hardware:

  • A big TV or projector for the "Main Screen" view that you can drive directly from a computer (e.g. chromecast likely will not work well.)
  • A stereo or sound system of some type (something better than laptop speakers).
  • Several reasonably powerful computers running linux (at least 3, preferably 5 per bridge).
  • A network router or switch which can support as many computers as you're planning to use. Note: a wired router or switch is strongly preferred both for performance reasons and for ease of configuration.
  • (Optional) decent microphone or headset if you want to use the speech recognition capabilities (need to reject background noise).

Step 0.5 Understanding the Software Components

It helps to have a basic understanding of how the system works in order to set it up and troubleshoot in case something doesn't work like you expect. The system is composed of the following linux processes:

  • ssgl_lobby - This process is the lobby server and is how all the other parts of the system find one another. There should be exactly one ssgl_server process running in your system, on one computer only. You will need to know the IP address of the system that the lobby process (ssgl_server) runs on. (Use the linux command ip addr show or ifconfig -a). The ssgl_lobby process has no graphics and no UI at all.
  • snis_multiverse - This keeps track of player ships and stores ship names, ship state, and ship password hashes. This is what allows ships to travel between solarsystems (between snis_server instances). There should be exactly one snis_multiverse process in your system. This process has no graphics and no UI at all.
  • snis_server - This runs the simulation of a solar system, its associated planets, starbases, nebula, NPC ships, etc. You need at least one snis_server, but may have more than one. This process has no graphics and no UI at all.
  • snis_client - This process is the face of SNIS, and is what the player interacts with. It is responsible for drawing all graphics and making all sounds. You need one snis_client process running for each player's computer plus one for the "Main Screen".
Note that the above diagram shows that snis_server, snis_multiverse, and ssgl_lobby are all running on the same computer that controls the projector and stereo, and this computer also runs a snis_client process to drive the projector and stereo. This is not a requirement. The snis_server, snis_multiverse, and ssgl_lobby processes could also run on any other computers reachable on the network. It's usually just easiest to use a big powerful desktop system for the "main screen" snis_client and then also run the server processes on that system as well, and means the other computers are simpler to set up, in that they are all identical, and only run a single process, snis_client.

Step 1. Preliminary Hardware Setup

The first thing that you need to do is get all the hardware into your game room, arranged on furniture in such a way that everyone can see the big TV or projector, connect it all up and make sure it is nominally working. That means:

  1. Figure out which computer will run ssgl_server, snis_multiverse, and snis_server. It is easiest if these will all run on the same computer, but this is not a requirement. For the purposes of these instructions we will assume this is the case, and we will refer to this system as the Main Computer. Usually this will also be the same computer which is connected to the projector (or big TV) and the stereo. Again, this is not a requirement, but we will assume this is the case.
  2. Boot up all your computers and make sure every computer can "ping" the Main Computer. If this doesn't work, the game won't work. Note, many wireless routers are configured to deliberately prevent local devices from talking to one another for security reasons on the assumption that they normally are only using the router to get to the internet, not to communicate amongst themselves. For this reason, and for performance reasons, a wired network switch or router is strongly preferred.

    Note: By default, the game assumes that the internet-facing network will be used. If you have a private network (the internet is inaccessible) or if your system is on multiple networks and you wish to use a network other than the default internet-facing network, special action will be required. Note also that it is not currently possible to play with a multi-network setup in which all the stations are not on the same network. That is, you cannot host the lobby server and snis_server on a multi-networked system and expect clients to be able to connect via more than one network. Currently, the lobby server and snis_server only server a single network, but you can choose which network.

    If you wish to run the game on a network other than the default internet-facing network, do the following prior to running snis_launcher:

    	export SSGL_PRIMARY_IP_ADDR_PROBE=192.168.1.1
    
    Of course you should replace "192.168.1.1" with some address that is on your desired network. It is not required that a host be present at the address you specify, this address is merely used to probe the host's routing table to find out which interface to use.

    If on the lobby screen, you see blinking red snis_server instances with IP addresses of 0.0.0.0 this indicates that the snis_server instances were not able to determine a network interface to use. Typically this means SSGL_PRIMARY_IP_ADDR_PROBE is not set, but should be (because the internet is inaccessible from your network), or is set to an invalid value, e.g. it is blank, or has a value which is not an IP address.

Step 2. Software Setup

  1. Install "Space Nerds In Space" on all computers. (See Build Instructions above). Note, you should install the same version on all computers. The protocol used by snis_server and snis_client to communicate with one another frequently changes, and if there is a mismatch, they won't be able to talk to each other (in fact, will refuse to talk to one another most likely.) Generally this means you should use the latest version from git on all computers.

Step 3. Setting up the Main Computer

There is a script to help with setting up: snis_launcher.

  1. Log into the Main Computer as a non-root user and run snis_launcher. You should see something like this (assuming your username is capnkirk):
    capnkirk@enterprise ~ $ cd github/space-nerds-in-space
    capnkirk@enterprise ~/github/space-nerds-in-space $ ./snis_launcher
    
         Welcome to Space Nerds In Space
    
    ------------------------------------------------------------
    No SNIS processes are currently running.
    ------------------------------------------------------------
    
       1. Launch SNIS lobby server
    	The lobby server allows clients to find servers
    	There should be one lobby server total.
       2. Launch SNIS multiverse server
    	The multiverse server stores player ship data
    	There should be one multiverse server total
       3. Launch SNIS server
    	There should be one snis server per solarsystem.
    	There should be at least one instance of snis_server.
       4. Launch SNIS client process
    	There should be one snis client process per player
    	plus one more per ship for the main screen.
       5. Stop all SNIS processes
       6. Stop all SNIS clients
       7. Stop all SNIS servers
       0. Quit
       Choose [0-7]:
    
  2. Select 1 to start the lobby server. You should see something like this:
    Starting the lobby server
    
    
         Welcome to Space Nerds In Space
    
    ------------------------------------------------------------
    The following SNIS processes are running:
            LOBBY SERVER -- capnkirk  6290  0.0  0.0  17232  2024 ?        Ssl  12:01   0:00 ./bin/ssgl_server
    ------------------------------------------------------------
    
    And then the menu will be displayed again.
  3. Choose 2 to start snis_multiverse. You should see something like this:
         Welcome to Space Nerds In Space
    
    ------------------------------------------------------------
    The following SNIS processes are running:
            LOBBY SERVER -- capnkirk  6290  0.0  0.0  25428  2024 ?        Ssl  12:01   0:00 ./bin/ssgl_server
       MULTIVERSE SERVER -- capnkirk  6313  0.0  0.0 170188  1724 pts/7    Sl+  12:03   0:00 ./bin/snis_multiverse localhost nickname narnia
    ------------------------------------------------------------
    
    and then the menu again.
  4. Choose 3 to start the snis_server process. You should see something like this:
    Choose a solar system:
       default
       default2
       karado
       polaris
       sirius
    Enter the name of the solarsystem:
    
    Type in the name of the solarsystem you want. You should see something like this:
    Enter the name of the solarsystem: default2
    Using solar system default2
    
         Welcome to Space Nerds In Space
    
    ------------------------------------------------------------
    The following SNIS processes are running:
            LOBBY SERVER -- capnkirk  6290  0.0  0.0  99160  2024 ?        Ssl  12:01   0:00 ./bin/ssgl_server
       MULTIVERSE SERVER -- capnkirk  6313  0.0  0.0 170188  2856 pts/7    Sl+  12:03   0:00 ./bin/snis_multiverse localhost nickname narnia
             SNIS SERVER -- capnkirk  6459  1.0  0.0 260608  9724 pts/7    Sl+  12:09   0:00 ./bin/snis_server -l localhost -g SPACENERDS -L DEFAULT2 x --enable-enscript -m narnia -s default2
    ------------------------------------------------------------
    
    You can repeat this step to start multiple instances of snis_server with different solar systems.
  5. Choose 4 to start a snis_client. This will be what runs the "Main Screen". You should briefly see something like:
    Starting snis_client
    
    
         Welcome to Space Nerds In Space
    
    ------------------------------------------------------------
    The following SNIS processes are running:
            LOBBY SERVER -- capnkirk  6290  0.0  0.0  99160  2024 ?        Ssl  12:01   0:00 ./bin/ssgl_server
       MULTIVERSE SERVER -- capnkirk  6313  0.0  0.0 186580  2856 pts/7    Sl+  12:03   0:00 ./bin/snis_multiverse localhost nickname narnia
             SNIS SERVER -- capnkirk  6459  1.5  0.0 277000 11772 pts/7    Sl+  12:09   0:04 ./bin/snis_server -l localhost -g SPACENERDS -L DEFAULT2 x --enable-enscript -m narnia -s default2
             SNIS CLIENT -- capnkirk  6583 94.0  0.9 708860 114848 pts/7   Rl+  12:14   0:00 ./bin/snis_client --fullscreen
    ------------------------------------------------------------
    
    This will quickly be covered over by the graphical display of the snis_client process which will look like this:

    network setup screen Make sure the MAIN SCREEN checkbox is checked.

    • If this is the very first time you have run the game, or if you intend to create a new ship with a name you have never used before, then check the "CREATE SHIP" checkbox. Otherwise leave the CREATE SHIP checkbox unchecked.
    • Leave the "JOIN SHIP" checkbox unchecked.
    • Since ssgl_server is running on the same system as snis_client (our Main Computer), it is fine to leave the LOBBY SERVER NAME OR IP ADDRESS field as "localhost".
    • Enter your ship's name and password (these you make up.)
    • Click on either of the ENTER LOBBY buttons. You should then see something like this, with one line for each snis_server that you started (in this case, one.):

      The lobby screen

  6. Click on the white text "DEFAULT2". When you do that, you should see:

    The lobby screen

  7. Click on the "CONNECT TO SERVER" button on the right side of the screen. After you do that, you should briefly see this:

    The connecting screen

    and after a short time, you should see the "main view", something like this:

    the main view

  8. Arrange things so this main view is appearing via your projector or big TV.
  9. Choose 0 to exit the snis_launcher script.
  10. Make a note of the IP address(es) of the system running ssgl_server (our Main Computer). Run
    capnkirk@enterprise$ ifconfig | grep 'inet addr'
              inet addr:10.0.0.3  Bcast:10.0.0.255  Mask:255.255.255.0
              inet addr:127.0.0.1  Mask:255.0.0.0
              inet addr:10.236.226.31  Bcast:10.255.255.255  Mask:255.224.0.0
    

Step 4. Setting up the Bridge Stations

Repeat the following steps for each bridge station.

  1. Run snis_launcher. You should see:
    capnkirk@enterprise $ ./snis_launcher
    
         Welcome to Space Nerds In Space
    
    ------------------------------------------------------------
    No SNIS processes are currently running.
    ------------------------------------------------------------
    
       1. Launch SNIS lobby server
    	The lobby server allows clients to find servers
    	There should be one lobby server total.
       2. Launch SNIS multiverse server
    	The multiverse server stores player ship data
    	There should be one multiverse server total
       3. Launch SNIS server
    	There should be one snis server per solarsystem.
    	There should be at least one instance of snis_server.
       4. Launch SNIS client process
    	There should be one snis client process per player
    	plus one more per ship for the main screen.
       5. Stop all SNIS processes
       6. Stop all SNIS clients
       7. Stop all SNIS servers
       0. Quit
       Choose [0-7]:
    
    Note that it shows "No SNIS processes are currently running." This is because this is a different computer (not the Main Computer).
  2. Choose 4 to start snis_client. You should briefly see something like this:
    Starting snis_client
    
    
         Welcome to Space Nerds In Space
    
    ------------------------------------------------------------
    The following SNIS processes are running:
             SNIS CLIENT -- capnkirk  7247 98.0  1.1 748036 142528 pts/7   Rl+  12:38   0:00 ./bin/snis_client --fullscreen
    --------------------------------------------------
    
    which will quickly be covered up by the network setup screen, something like this:

    The network setup screen

    • Make sure MAIN SCREEN checkbox is not checked.
    • Make sure SOUND SERVER ROLE checkbox is not checked.
    • Make sure TEXT TO SPEECH checkbox is not checked.
    • Make sure CREATE SHIP checkbox is not checked.
    • Make sure JOIN SHIP checkbox is checked.
    • You may want to restrict each station to specific roles
    • If you hover your mouse in the upper left hand corner of the screen a small menu with the detected lobby servers will appear. You can select the detected lobby host here by clicking on it..
    • If the lobby is not autodetected, for LOBBY SERVER NAME OR IP ADDRESS enter the IP address that you noted for the MAIN COMPUTER in step 10, above.
    • For SHIP NAME and PASSWORD, enter the same name and password you used for the Main Computer setup in step 5 above.
    • Click the ENTER LOBBY XXX.XXX.XXX.XXX button if the lobby is autodetected, otherwise use the 2nd ENTER LOBBY button to choose the lobby with the IP address you have typed in. You should then see something like this, with one line for each snis_server that you started (in this case, one.):

      The lobby screen

  3. Click on the white text "DEFAULT2". When you do that, you should see:

    The lobby screen

  4. Click on the "CONNECT TO SERVER" button on the right side of the screen. After you do that, you should see the snis_client graphical display appear. Which screen it ends up on depends on what ROLES were selected on the network setup screen.
  5. Use the function keys to select the appropriate station for this console (e.g. if you mean for this to be the NAVIGATION station, press F2).

That's it for the bridge station setup. Repeat for each station.

To use the voice chat feature, you can press and hold F12 and whatever your microphone records will be transmitted to the other terminals on your ship. If you press and hold ctrl-F12, then whatever your microphone records will be transmitted to all other terminals on all ships in the current snis_server instance.


Updating Space Nerds In Space

Suppose you have set up Space Nerds In Space previously but development has moved on and now what's in github and on the assets server is newer than what you have, or that you have several players together to play the game but they each have a different version of Space Nerds In Space. How do you sync up your game with the latest stuff?

Use the following procedure:

	cd space-nerds-in-space;	# Or wherever you checked out the code
	git checkout master;		# Just in case you switched branches
	make mostly-clean;		# Let's start fresh
	git pull;			# Fetch the new code from github
	make;				# Build everything
	make update-assets;		# Fetch any new or updated art

Talking to "The Computer" (how to set up speech recognition)

Anything you can type into "the computer" via the Navigation screen or the Comms screen, you can also just speak, provided you set things up. There are two methods by which you can do speech recognition: local, pocketsphinx-based speech recognition, and Android based speech recognition using your phone or other Android device. Both methods are done outside of Space Nerds In Space proper, and feed the text of the recognized speech into snis_client through a fifo: /tmp/snis-natural-language-fifo. For that matter, you can echo text directly into this fifo if you want to, e.g.:

	echo "turn right forty five degrees" > /tmp/snis-natural-language-fifo
  • Pocketsphinx based speech-recognition

    You must install some packages:

    sudo apt-get install libttspico-utils; # for text to speech sudo apt-get install espeak; # optional alternative to libttspico-utils sudo apt-get install sox; # for "play" command, used by text to speech sudo apt-get install alsa-utils; # optional alternative to sox, for "aplay" command

    And for the pocketsphinx based speech recognition:

    sudo apt-get install pocketsphinx-utils; sudo apt-get install pocketsphinx-lm-en-hub4; sudo apt-get install pocketsphinx-lm-en-hub4; sudo apt-get install libpocketsphinx1;

    Once these are installed, on a machine that is running snis_client, you can then open up a terminal window and run (as a non-root user)speech/queeg500 This will start up pocketsphinx listening on the default microphone to recognize text and feed it into /tmp/snis-natural-language-fifo. If you're wondering why it's called queeg500, this is the reason. You must begin every spoken command with "Computer". For example, try saying: "Computer, Ramming speed!"

  • Android based speech recognition

    There is an Android app called Space Nerds Communicator which is very simple and just allows your Android device to do speech recognition and forward the resulting text to a specified IP address and port. By default the port is 8080.

    To use it, find out the IP address your machine running snis_client (e.g. run ip addr show or ifconfig -a), and open up a terminal window on this machine. Run the following command (as a non-root user):
    	netcat -lvk -p 8080 > /tmp/snis-natural-language-fifo
    
    This starts up a netcat process listening for connections on port 8080 (or choose another port). Netcat just copies whatever comes in to its stdout, which in this case is redirected into /tmp/snis-natural-language-fifo.

    Then run the Space Nerds Communicator app on your Android device, and configure the IP address and port to match your snis_client machine. Then tap the microphone button and speak your commands. The app will send them to netcat, which will then feed them into the fifo.

    Note that with the Android app, you should not precede your commands with "Computer". For example, use "Ramming speed!" not "Computer, ramming speed!"


Troubleshooting

Contents:
  1. Using Joysticks and Controllers
  2. Bridge Verification Failed
  3. Audio Problems
  4. OpenGL versions
  5. The game is crashing!
  6. network problems
  7. Playing over the internet

  1. Using Joysticks and Controllers

    There is a config file in share/snis/joystick_config.txt that can be used to configure the game to understand your usb controllers.

    • Step 1: Figure out what your controllers are called. Look in /dev/input/by-id for names that end with "-joystick" and do not end with "-event-joystick". For example:
      	$ ls -l /dev/input/by-id
      	total 0
      	lrwxrwxrwx 1 root root 9 Nov  9 07:13 usb-0461_USB_Optical_Mouse-event-mouse -> ../event8
      	lrwxrwxrwx 1 root root 9 Nov  9 07:13 usb-0461_USB_Optical_Mouse-mouse -> ../mouse0
      	lrwxrwxrwx 1 root root 9 Nov  9 07:13 usb-0461_Wired_USB_Keyboard-event-if01 -> ../event7
      	lrwxrwxrwx 1 root root 9 Nov  9 07:13 usb-0461_Wired_USB_Keyboard-event-kbd -> ../event6
      	lrwxrwxrwx 1 root root 9 Nov 10 10:54 usb-Thrustmaster_T.16000M-event-joystick -> ../event5
      	lrwxrwxrwx 1 root root 6 Nov 10 10:54 usb-Thrustmaster_T.16000M-joystick -> ../js1
      	lrwxrwxrwx 1 root root 9 Nov 10 10:54 usb-Thrustmaster_TWCS_Throttle-event-joystick -> ../event4
      	lrwxrwxrwx 1 root root 6 Nov 10 10:54 usb-Thrustmaster_TWCS_Throttle-joystick -> ../js0
      
      In this case, we see we have two devices of interest, usb-Thrustmaster_T.16000M-joystick and usb-Thrustmaster_TWCS_Throttle-joystick.
    • Step 2: Figure out what the buttons and axes for your devices are. There is a test program included with Space Nerds In Space called "joystick_test". Run this program, and you should see something like:
      	capnkirk@enterpise $ ./joystick_test
      	usb-Thrustmaster_T.16000M-joystick
      	usb-Thrustmaster_TWCS_Throttle-joystick
      	Discovered 2 joysticks
      	  0: usb-Thrustmaster_T.16000M-joystick
      	  1: usb-Thrustmaster_TWCS_Throttle-joystick
      	Device: 0, time 99672500, value        0, type: 129, axis/button: 0
      	Device: 1, time 99672520, value   -32767, type: 130, axis/button: 6
      	Device: 0, time 99672520, value        0, type: 130, axis/button: 5
      	[... many lines omitted ...]
      	Device: 1, time 99672520, value   -32767, type: 130, axis/button: 7
      	Device: 1, time 99672524, value        0, type: 130, axis/button: 8
      	Device: 1, time 99672524, value        0, type: 130, axis/button: 9
      
      Here we see two devices, Device 0, and Device 1, corresponding to the usb-Thrustmaster_T.16000M-joystick and the usb-Thrustmaster_TWCS_Throttle-joystick. We can press the buttons on the devices and move the axes and this will cause more output to be printed. For example, moving the throttle controller:
      	Device: 1, time 99830028, value   -29041, type:   2, axis/button: 2
      	Device: 1, time 99830168, value   -28732, type:   2, axis/button: 2
      	Device: 1, time 99830196, value   -21727, type:   2, axis/button: 2
      	Device: 1, time 99830224, value   -18962, type:   2, axis/button: 2
      	Device: 1, time 99830308, value   -18918, type:   2, axis/button: 2
      
      Here we see that the throttle axis is on device 1 (usb-Thrustmaster_TWCS_Throttle-joystick.) and on axis 2. Make a note of this. Pressing one of the buttons on the joystick, we see:
      	Device: 0, time 99919292, value        1, type:   1, axis/button: 0
      	Device: 0, time 99919388, value        0, type:   1, axis/button: 0
      
      Here we see that this button is button 0 on the usb-Thrustmaster_T.16000M-joystick. Make a note of this. Continue to do this with each axis and button you are interested in, making a note of the button numbers and axis numbers.
    • Step 3: Modify share/snis/joystick_config.txt to add or modify the configuration for your devices. First check to see if there is already a configuration for your device. Look for a line in the file that begins:
      	device:your-device-name
      
      If there is such a line, there is already a configuration for your device and you just need to modify it to suit your taste. If there is no such line, you need to add a new device configuration. Go to the bottom of the file and add
      	device:your-device-name
      
      where "your-device-name" is the name of your device. Note, this is actually a regular expression so if your device name contains a serial number it is possible to write a generic name that will ignore the serial number part, but for most devices, just using the device name as is will be fine.

      Follow the other examples to add mappings from your device buttons and axes to game functions for each appropriate game mode. The game functions are:

      • damcon-gripper
      • damcon-pitch
      • damcon-roll
      • nav-attitude-indicator-abs-rel
      • nav-change-pov
      • nav-docking-magnets
      • nav-engage-warp
      • nav-nudge-warp-down
      • nav-nudge-warp-up
      • nav-nudge-zoom-down
      • nav-nudge-zoom-up
      • nav-reverse
      • nav-standard-orbit
      • nav-starmap
      • phaser
      • pitch
      • roll
      • throttle
      • torpedo
      • weapons-pitch
      • weapons-yaw
      • yaw
      The game modes are:
      • mode 0 - main screen
      • mode 1 - navigation
      • mode 2 - weapons
      • mode 3 - engineering
      • mode 4 - science
      • mode 5 - comms
      • mode 6 - demon screen
      • mode 7 - damage control
      So for example, if you have a "super-duper-brand-controller", and you want the Navigation screen to map axis 5 to yaw, axis 6 to pitch, and button 3 engage warp, you would write:
      device:super-duper-brand-controller
       mode 1 axis 5 yaw
       mode 1 axis 6 pitch
       mode 1 button 3 nav-engage-warp
      

  2. I keep getting "BRIDGE VERIFICATION FAILED" -- what am I doing wrong?

    This means one of several things:

    1. If you have checked the "CREATE SHIP" checkbox: Either:
      • You meant to create a new ship with the given name, but a ship with that name has already been created. In that case, choose a different name for your ship.
      • You meant to re-use an existing ship. In that case, uncheck the "CREATE SHIP" checkbox. If the ship is already running in the game (other players are onboard) check the JOIN SHIP checkbox. If the ship is not yet in the game (but has been used before and is recorded) then uncheck the JOIN SHIP checkbox.
    2. If you have not checked the "CREATE SHIP" checkbox:
      • If you have checked the "JOIN SHIP" checkbox: One of the following has occurred:
        • You have entered the name of an existing ship, and entered the password correctly, but this ship is only known from past runs, the ship has not entered the solar system where you are trying to join it. In that case, uncheck the JOIN SHIP checkbox.
        • You have entered the name of a ship which does not exist, or mistyped the name of the ship. Enter the name of a ship which exists.
        • You have entered the name of an existing ship, but entered an incorrect password.
      • If you have not checked the "JOIN SHIP" checkbox. This means that one of the following has occurred:
        • You intended to start up a previously used ship in a solarsystem but that ship is already in the solarsystem with players on it. You need to check the "JOIN SHIP" checkbox.
        • You have entered an incorrect ship name.
        • You have entered an incorrect ship password.
    3. What is with this "JOIN SHIP" and "CREATE SHIP" checkbox crap? Why is it so confusing?

      "CREATE SHIP" has to do with whether snis_multiverse knows about your shipname/password. The snis_multiverse process maintains a database of shipname/password hashes which is persistent across invocations. However snis_server also has a notion of whether a ship is known to it. When you check "CREATE SHIP", you are telling snis_server to tell snis_multiverse to create a new ship. If snis_multiverse thinks the ship already exists, you will get BRIDGE VERIFICATION FAILURE. The "JOIN SHIP" checkbox means that you are attempting to join a ship that snis_server already knows about -- that means, a ship that already has other snis_clients attached to it. If you are the first snis_client in a session to use a ship, you should not check JOIN SHIP. If you are not the first snis_client to use a ship name, then you should check JOIN SHIP.

      Basically it is about intent. The game needs to know the difference between intentionally creating a new ship vs. mistyping a ship name, and the difference between creating a new ship and joining an existing ship. Not to suggest that there isn't room for improvement in how it works.

    4. I made a ship, but I forgot the password, what can I do?

      Or you made a ship, and you want to delete it. You cannot recover the password, or recover the ship. You can delete the ship and make a new one with the same name though. First, make sure the game is not running. Use snis_launcher and select the "Stop all SNIS processes" option on the system that is running snis_multiverse. Then, on the system that runs snis_multiverse, look for a directory called snisdb. Let's say you named your ship enterprise, and you want to delete it and create a new one with the same name.

      capnkirk@enterprise ~/github/space-nerds-in-space $ ls -l snisdb/*/*/*
      -rw-r--r-- 1 capnkirk capnkirk 5370 Jul 19 18:36 snisdb/2aa8/3672/2aa83672bace43178acab8e73b7391d1c316e80d.data
      -rw-r--r-- 1 capnkirk capnkirk 5241 Jul 19 18:36 snisdb/80f2/969e/80f2969eded0cb559081e3e3202c94fcb5917a41.data
      -rw-r--r-- 1 capnkirk capnkirk 5355 Jul 19 18:36 snisdb/82b2/4d25/82b24d25b042724aa94a39a9ea38e05cf0cf6340.data
      -rw-r--r-- 1 capnkirk capnkirk 5241 Jul 19 18:36 snisdb/d253/706d/d253706d8cecf7537337da834ea7d48894f0618f.data
      -rw-r--r-- 1 capnkirk capnkirk 5432 Jul 19 18:36 snisdb/e7d9/fa36/e7d9fa368467e5549e6846be3d8d11ebac751851.data
      -rw-r--r-- 1 capnkirk capnkirk 5427 Jul 19 18:36 snisdb/fc4c/c56a/fc4cc56a58319495465a36128e65d1dcf69b2c08.data
      capnkirk@enterprise ~/github/space-nerds-in-space $ grep enterprise snisdb/*/*/*
      snisdb/e7d9/fa36/e7d9fa368467e5549e6846be3d8d11ebac751851.data:sdata.name:enterprise
      
      From this we can see that the data for the "enterprise" ship (including the hashed password) is stored in snisdb/e7d9/fa36/e7d9fa368467e5549e6846be3d8d11ebac751851.data

      Delete this file.

      capnkirk@enterprise ~/github/space-nerds-in-space $ rm snisdb/e7d9/fa36/e7d9fa368467e5549e6846be3d8d11ebac751851.data
      

      Now you should be able to create a new ship with the name "enterprise" in the usual way.


  3. Sound isn't working! (Or sound isn't working quite as I expected)

    Audio on linux is complicated. In general, there are two main takes on how audio should work in linux, "the pulse way", and "the JACK way". The "JACK way" is generally concerned with professional audio recording, very low latency, etc. The "pulse way" is less concerned with such things, and is more concerned with "just make some damn sound work." I'm going to assume you're using the "pulse way," since if you're using JACK, you probably already know what you're doing and can troubleshoot it yourself.

    Space Nerds in Space uses the Portaudio library for sound. You need version 1.9 of portaudio (not 2.0). There is a test program, snis_test_audio to help trace down audio problems. It will print out a list of devices that Portaudio knows about. Often, when there is some audio problem, the problem turns out to be that sound is by default playing on a different device than what you expected.

    Here is an example of running the snis_test_audio program on my system:

    $ make snis_test_audio
    $ ./snis_test_audio
    Space Nerds In Space audio test program.
    ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.rear
    ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.center_lfe
    ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.side
    ALSA lib pcm_route.c:867:(find_matching_chmap) Found no matching channel map
    connect(2) call to /dev/shm/jack-1000/default/jack_0 failed (err=No such file or directory)
    attempt to connect to server failed
    Portaudio reports 21 sound devices.
    Portaudio says the default device is: 20
    wwviaudio_initialize_portaudio returned 0
    Portaudio reports 21 devices
    0: HDA Intel PCH: ALC887-VD Analog (hw:0,0)
    1: HDA Intel PCH: ALC887-VD Digital (hw:0,1)
    2: HDA Intel PCH: ALC887-VD Alt Analog (hw:0,2)
    3: HDA Intel PCH: HDMI 0 (hw:0,3)
    4: HDA Intel PCH: HDMI 1 (hw:0,7)
    5: HDA Intel PCH: HDMI 2 (hw:0,8)
    6: Scarlett 2i2 USB: Audio (hw:1,0)
    7: sysdefault
    8: front
    9: surround21
    10: surround40
    11: surround41
    12: surround50
    13: surround51
    14: surround71
    15: iec958
    16: spdif
    17: hdmi
    18: pulse
    19: dmix
    20: default
    Attempting to play sound... ...finished attempting to play sound
    
    You can try alternate devices, for example, I can make it play through my Scarlett 2i2 USB sound device by:
    $ ./snis_test_audio 6
    Space Nerds In Space audio test program.
    Manually setting sound device to 6
    ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.rear
    ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.center_lfe
    ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.side
    ALSA lib pcm_route.c:867:(find_matching_chmap) Found no matching channel map
    connect(2) call to /dev/shm/jack-1000/default/jack_0 failed (err=No such file or directory)
    attempt to connect to server failed
    Portaudio reports 21 sound devices.
    Portaudio says the default device is: 20
    Using sound device 6
    wwviaudio_initialize_portaudio returned 0
    Portaudio reports 21 devices
    0: HDA Intel PCH: ALC887-VD Analog (hw:0,0)
    1: HDA Intel PCH: ALC887-VD Digital (hw:0,1)
    2: HDA Intel PCH: ALC887-VD Alt Analog (hw:0,2)
    3: HDA Intel PCH: HDMI 0 (hw:0,3)
    4: HDA Intel PCH: HDMI 1 (hw:0,7)
    5: HDA Intel PCH: HDMI 2 (hw:0,8)
    6: Scarlett 2i2 USB: Audio (hw:1,0)
    7: sysdefault
    8: front
    9: surround21
    10: surround40
    11: surround41
    12: surround50
    13: surround51
    14: surround71
    15: iec958
    16: spdif
    17: hdmi
    18: pulse
    19: dmix
    20: default
    Attempting to play sound... ...finished attempting to play sound
    

    So, you can see what devices it thinks you have, and try them out.

    I also made it so snis_client can use alternate sound devices, e.g.

    export SNIS_AUDIO_DEVICE=6
    
    then launch the game and it will play sounds through my Scarlett 2i2 USB device instead of the default device.

    Another thing worth trying. On my system (Mint 18.1) there is a "Sound Settings..." thing that I can play with. When the game is running, it shows "ALSA plug-in [snis_client]: ALSA Playback on", and from this GUI Sound Setting thing, I can dynamically switch it to play on either "Built-in Audio Analog Stereo" (which I think is probably what portaudio calls "0: HDA Intel PCH: ALC887-VD Analog (hw:0,0)", and the Scarlett 2i2. But I think that is via pulse, so if snis_test_audio shows "pulse" as a device it knows, then you should probably do: export SNIS_AUDIO_DEVICE={whatever number portaudio thinks pulse is according to snis_test_audio output} (You can install pulse and pavucontrol if they aren't installed and see if that helps. The pavucontrol program should let you dynamically control to which device a running program's sound output is directed.

    Note: I have seen the sound get stuck on a per-program basis to a particular audio device. For example, I used the "Sound Settings..." to set the audio output to HDMI for Space Nerds In Space. Later, I disconnected the HDMI cable. The sound output remained stuck to HDMI, however, since there was no HDMI cable plugged in, the HDMI interface doesn't even show up in the Sound Settings. However other programs which used portaudio (e.g. Word War Vi) continued to work just fine. I was able to fix this using pavucontrol (which is will show the HDMI sound interface even if no HDMI cable is connected), or by manually using the SNIS_AUDIO_DEVICE environment variable to override the default.


  4. OpenGL version problems

    For most recent versions of Space Nerds In Space, OpenGL version 2.1 (aka "#version 120" (See OpenGL version decoder ring)) is required. This is quite old, so your computer probably supports it.

    For awhile OpenGL version 3.0 (aka "#version 130") was required. This is no longer the case.

    Historically, the following OpenGL versions were required:

    Feb 17, 2019 - Present OpenGL 2.1 Commit fa60c565411db509a9dccaf4a83ec2dfc7951a00
    Apr 12, 2018 - Feb 16, 2019 OpenGL 3.0 Commit 3c8ea5c71021b3eb3ede34543013d30cce117529
    Dec 22, 2013 - Apr 11, 2018 OpenGL 2.1 Commit fad901a5602c1edecab75e6cc1171e9c6f39cfe5
    Aug 31, 2013 - Dec 22, 2013 Very old OpenGL (fixed pipeline) Commit 8b039d60cf96a08b69f394a9ee07c8f2a928b8da
    Nov 3, 2012 - Aug 31, 2013 No OpenGL required at all Commit f421da62ce8d7a0b5e489e78a77e526d7448a62e (first commit)

    From Apr 12, 2018 until Feb 17, 2019, the shaders used by Space Nerds In Space required OpenGL version 3.0 (aka "#version 130") or better. If your computer does not support a recent enough version of OpenGL, you can run the limited client instead, which does not use OpenGL at all. Be sure to de-select MAIN SCREEN and WEAPONS roles on the login screen, as these screens do not work well with the limited client. The remaining should work sufficiently well with the limited client, although NAVIGATION and especially the DEMON screen will probably exhibit poor performance and reduced FPS, so it's best to use the limited client only for ENGINEERING, DAMAGE CONTROL, COMMS, and SCIENCE.

    NOTE: The limited client is not as well tested as the OpenGL client, so you are more likely to encounter bugs.


  5. The game is crashing! What can I do?

    Suppose you see something like this ("Segmentation fault"):

    snis_multiverse: hash 82b24d25b042724aa94a39a9ea38e05cf0cf6340 exists, as expected.
    snis_multiverse: checking hash 82b24d25b042724aa94a39a9ea38e05cf0cf6340
    snis_multiverse: verify existence pass=1
    snis_multiverse: looking up hash '82b24d25b042724aa94a39a9ea38e05cf0cf6340'
    snis_multiverse: checking against '2aa83672bace43178acab8e73b7391d1c316e80d'
    snis_multiverse: checking against '80f2969eded0cb559081e3e3202c94fcb5917a41'
    snis_multiverse: checking against '82b24d25b042724aa94a39a9ea38e05cf0cf6340'
    snis_multiverse: match hash '82b24d25b042724aa94a39a9ea38e05cf0cf6340'
    Segmentation fault
    capnkirk@enterprise ~/github/space-nerds-in-space $ Last buffer length read from socket 14 was 67
    32 30 31 37 2d 30 33 2d 30 34 20 30 37 3a 35 39 3a 30 30 20 64 31 39 64 62 64 66 30 62 39 33 38 30 34 62 63 62 65 35 36 66 31 33 64 34 66 33 32 63 63 62 34 39 32 33 31 63 37 32 34 20 2b 20 33 36 38 00 
    snis_server: client refcount = 1
    snis_server: client refcount = 0
    snis_server: client count of bridge 0 = 0
    snis_server: calling remove_client 0
    snis_server: remove_client 0 returned
    
    First, see if you can make it happen reliably. If you can, then do the following: Here is a summary of what to do (more detailed instructions are below).
    1. make mostly-clean
    2. make O=0 # Capital letter O = zero -- suppress optimization.
    3. ulimit -c unlimited
    4. Reproduce the problem with the unoptimized program and obtain a core file.
    5. Figure out which program the core file came from (most likely, snis_client but could be something else, like snis_server or snis_multiverse.)
    6. file core
    7. gdb -c core bin/snis_client
    8. (gdb) bt
    9. Capture the output of gdb and paste it into a bug report.
    Here is a more detailed version of the above instructions.
  1. Try to capture a core dump
    	$ ulimit -c unlimited
    
    Then run the game again. This time you should see something like this for example:
    Replacing ./share/snis/solarsystems/default/../../textures/planet-texture4-4.png with ./share/snis/solarsystems/karado/ounii-with-clouds-4.png
    Replacing ./share/snis/solarsystems/default/../../textures/planet-texture4-5.png with ./share/snis/solarsystems/karado/ounii-with-clouds-5.png
    Replacing ./share/snis/solarsystems/default/../../textures/planet-texture4-0.png with ./share/snis/solarsystems/karado/ounii-with-clouds-0.png
    Replacing ./share/snis/solarsystems/default/../../textures/planet-texture4-2.png with ./share/snis/solarsystems/karado/ounii-with-clouds-2.png
    snis_text_to_speech.sh Leaving high security area.
    Segmentation fault (core dumped)
    capnkirk@enterprise ~/github/space-nerds-in-space $ Last buffer length read from socket 14 was 16
    
    The "(core dumped)" means a memory image of the game was captured in a file named "core" (or maybe "core.xxxxxx", where xxxxxx is some numbers.) Run the following command:
    	$ ls -ltr | tail -5
    	-rwxr-xr-x 1 capnkirk capnkirk    850856 Mar  4 07:59 snis_server
    	-rwxr-xr-x 1 capnkirk capnkirk   1193104 Mar  4 07:59 snis_client
    	-rwxr-xr-x 1 capnkirk capnkirk    909616 Mar  4 07:59 snis_limited_client
    	-rwxr-xr-x 1 capnkirk capnkirk    212432 Mar  4 07:59 snis_multiverse
    	-rw------- 1 capnkirk capnkirk 417386496 Mar  4 08:17 core
    
  2. See if we can get any information out of the core file with the debugger, gdb. Run the following command:
    	$ $ file core
    	core: ELF 64-bit LSB core file x86-64, version 1 (SYSV), SVR4-style, from 'bin/snis_client --fullscreen --starship spacenerd --pw spacenerd'
    
    From this, we can see that the core file came from the snis_client program (rather than from snis_server, snis_multiverse, or something else.) Now that we know what program the core file is from, we can try to get a bit more info out of it. Run the following:
    	$ gdb -c core ./snis_client
    	$ gdb -c core
    	GNU gdb (Ubuntu 7.11.1-0ubuntu1~16.04) 7.11.1
    	Copyright (C) 2016 Free Software Foundation, Inc.
    	License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
    	This is free software: you are free to change and redistribute it.
    	There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
    	and "show warranty" for details.
    	This GDB was configured as "x86_64-linux-gnu".
    	Type "show configuration" for configuration details.
    	For bug reporting instructions, please see:
    	<http://www.gnu.org/software/gdb/bugs/>
    	Find the GDB manual and other documentation resources online at:
    	<http://www.gnu.org/software/gdb/documentation/>
    	For help, type "help".
    	Type "apropos word" to search for commands related to "word".
    	[New LWP 6365]
    	[New LWP 6386]
    	[New LWP 6371]
    	[New LWP 6375]
    	[New LWP 6372]
    	[New LWP 6373]
    	[New LWP 6385]
    	[New LWP 6374]
    	Core was generated by `./snis_client --fullscreen --starship spacenerd --pw spacenerd'.
    	Program terminated with signal SIGSEGV, Segmentation fault.
    	#0  0x0000000000431960 in ?? ()
    	[Current thread is 1 (LWP 6365)]
    	(gdb) _
    
    At this point, you're running gdb and it is waiting for you to tell it what to do. We can already see some information though. The program terminated with SIGSEGV (segmentation fault, we already knew that).

    Now type bt to see a back trace:

    	(gdb) bt
    	#0  0x0000000000431960 in ?? ()
    	#1  0x000000000044de3b in ?? ()
    	#2  0x00000000006fb480 in ?? ()
    	#3  0x00000000004752dd in ?? ()
    	#4  0x00007ffc221ca910 in ?? ()
    	#5  0x00000001bc70f20e in ?? ()
    	#6  0x00007ffc221ca900 in ?? ()
    	#7  0x00007ffc221f3cd5 in ?? ()
    	#8  0x00007ffc221ca930 in ?? ()
    	#9  0x000000017fffffff in ?? ()
    	#10 0x0000000000000001 in ?? ()
    	#11 0xa4ef74cf09462800 in ?? ()
    	#12 0x00007ffc221ca968 in ?? ()
    	#13 0x0000000000000000 in ?? ()
    	(gdb) _
    
    Not very helpful. Type quit to exit gdb.
    	(gdb) quit
    	$ _
    
    This is because the program was built optimized and stripped of debugging symbols (to make it smaller). So now we should try to recreate the problem with an unoptimized version of the program with debugging symbols. To make an unoptimized build, do the following:
    	$ make mostly-clean
    	... lots of output omitted ...
    	$ make O=0
    	  COMPILE mathutils.c
      	  COMPILE snis_alloc.c
      	  COMPILE snis_socket_io.c
      	  COMPILE snis_marshal.c
    	... lots of output omitted ...
    	  LINK snis_server
    	  LINK snis_client
    	  LINK snis_limited_client
    	  LINK snis_multiverse
    
    Now, try to recreate the problem by running the unoptimized game. Presuming you're successful at recreating the problem, you should have a new core file.
    	$ ls -ltr | tail -5
    	-rwxr-xr-x 1 capnkirk capnkirk   1410480 Mar  4 08:37 snis_client
    	-rwxr-xr-x 1 capnkirk capnkirk   1124344 Mar  4 08:37 snis_limited_client
    	-rwxr-xr-x 1 capnkirk capnkirk    237352 Mar  4 08:37 snis_multiverse
    	drwxr-xr-x 2 capnkirk capnkirk      4096 Mar  4 08:37 bin
    	-rw------- 1 capnkirk capnkirk 417390592 Mar  4 08:39 core
    
    Let's run the debugger on the new core file:
    	$ file core
    	core: ELF 64-bit LSB core file x86-64, version 1 (SYSV), SVR4-style, from './snis_client --fullscreen --starship spacenerd --pw spacenerd'
    	capnkirk@enterprise ~/github/space-nerds-in-space $ gdb -c core ./snis_client
    	GNU gdb (Ubuntu 7.11.1-0ubuntu1~16.04) 7.11.1
    	Copyright (C) 2016 Free Software Foundation, Inc.
    	License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
    	This is free software: you are free to change and redistribute it.
    	There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
    	and "show warranty" for details.
    	This GDB was configured as "x86_64-linux-gnu".
    	Type "show configuration" for configuration details.
    	For bug reporting instructions, please see:
    	<http://www.gnu.org/software/gdb/bugs/>.
    	Find the GDB manual and other documentation resources online at:
    	<http://www.gnu.org/software/gdb/documentation/>.
    	For help, type "help".
    	Type "apropos word" to search for commands related to "word"...
    	Reading symbols from ./snis_client...done.
    	[New LWP 6866]
    	[New LWP 6851]
    	[New LWP 6867]
    	[New LWP 6850]
    	[New LWP 6848]
    	[New LWP 6841]
    	[New LWP 6849]
    	[New LWP 6847]
    	[Thread debugging using libthread_db enabled]
    	Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
    	Core was generated by `./snis_client --fullscreen --starship spacenerd --pw spacenerd'.
    	Program terminated with signal SIGSEGV, Segmentation fault.
    	#0  0x000000000043c305 in vec3_init (vo=0x7c, x=221934.969, y=-5072.68408, z=175696.594) at quat.c:419
    	419		vo->v.x = x;
    	[Current thread is 1 (Thread 0x7fb02f7fe700 (LWP 6866))]
    	(gdb) _
    
    Now we see some more information. It's telling us the program crashed in the function called vec3_init in the file quat.c at line 419 and it's even showing use the line of source code where the program crashed. This is perfect information to put into bug report. Type bt to get a back trace:
    	(gdb) bt
    	#0  0x000000000043c305 in vec3_init (vo=0x7c, x=221934.969, y=-5072.68408, z=175696.594) at quat.c:419
    	#1  0x0000000000433034 in update_entity_pos (e=0x0, x=221934.969, y=-5072.68408, z=175696.594) at entity.c:189
    	#2  0x0000000000456383 in laserbeam_move (o=0x7da290 <go+938448>) at snis_client.c:1335
    	#3  0x0000000000456774 in init_laserbeam_data (o=0x7da290 <go+938448> at snis_client.c:1389
    	#4  0x000000000045587e in update_laserbeam (id=887, timestamp=243, origin=293, target=354) at snis_client.c:1143
    	#5  0x00000000004628ba in process_update_laserbeam () at snis_client.c:5386
    	#6  0x0000000000462fdf in gameserver_reader (arg=0x0) at snis_client.c:5586
    	#7  0x00007fb07228d6ba in start_thread (arg=0x7fb02f7fe700) at pthread_create.c:333
    	#8  0x00007fb071dba82d in clone () at ../sysdeps/unix/sysv/linux/x86_64/clone.S:109
    	(gdb) 
    
    Now it's showing us all the function calls along the way that lead up to the crash within the vec3_init function, which is more great info to put into a bug report. This is probably sufficient. But, if you want to go a little further...
    	(gdb) list
    	414		quat_init_axis_v(q, &v, angle);
    	415	}
    	416	
    	417	void vec3_init(union vec3 *vo, float x, float y, float z)
    	418	{
    	419		vo->v.x = x;
    	420		vo->v.y = y;
    	421		vo->v.z = z;
    	422	}
    	423	
    
    Unless you know C, that probably doesn't mean much to you. If you do know C, you can see that "vo" is a pointer to a union, and the function is setting several members of the union, and there aren't any other pointers in the vicinity, so let's look at vo.
    	(gdb) print vo
    	$1 = (union vec3 *) 0x7c
    	(gdb) _
    
    Hmm, 0x7c does not look especially like a valid memory address.
    	(gdb) print *vo
    	Cannot access memory at address 0x7c
    	(gdb) _
    
    Nope, it's not valid. Digging a little more, let's go up the stack and see what called this vec3_init() function.
    	(gdb) up
    	#1  0x0000000000433034 in update_entity_pos (e=0x0, x=221934.969, y=-5072.68408, z=175696.594) at entity.c:189
    	189		vec3_init(&e->e_pos, x, y, z);
    	(gdb) list
    	184		}
    	185	}
    	186	
    	187	void update_entity_pos(struct entity *e, float x, float y, float z)
    	188	{
    	189		vec3_init(&e->e_pos, x, y, z);
    	190	}
    	191	
    	192	void update_entity_orientation(struct entity *e, const union quat *orientation)
    	193	{
    	(gdb) print e
    	$2 = (struct entity *) 0x0
    
    Hmm, e is null, but was passed in here, so let's go up the stack again.
    	(gdb) up
    	#2  0x0000000000456383 in laserbeam_move (o=0x7da290 <go+938448> at snis_client.c:1335
    	1335		update_entity_pos(o->entity, x, y, z);
    	(gdb) list
    	1330	
    	1331		x = origin->x + 0.5 * target_vector.v.x;
    	1332		y = origin->y + 0.5 * target_vector.v.y;
    	1333		z = origin->z + 0.5 * target_vector.v.z;
    	1334	
    	1335		update_entity_pos(o->entity, x, y, z);
    	1336		update_entity_orientation(o->entity, &orientation);
    	1337		update_entity_material(o->entity, o->tsd.laserbeam.material);
    	1338		update_entity_non_uniform_scale(o->entity, length, 2.0 + snis_randn(7), 0.0);
    	1339	
    	(gdb) print o
    	$3 = (struct snis_entity *) 0x7da290 <go+938448>
    	(gdb) print o->entity
    	$4 = (struct entity *) 0x0
    	(gdb)
    
    So o seems to be a valid pointer, but o->entity is 0 (means NULL). So it seems we have an unexpected null pointer.
  • Network Problems
    • Connectivity problems

      First make sure your computers can ping each other. You can find out the IP address of your computer via ifconfig -a or ip a.

      capnkirk@enterprise ~ $ ifconfig
      enp3s0    Link encap:Ethernet  HWaddr 30:5a:3a:78:f9:d8
                inet addr:192.168.1.157  Bcast:192.168.1.255  Mask:255.255.255.0
                inet6 addr: fe80::29fe:4469:7af1:2fcb/64 Scope:Link
                UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
                RX packets:18743 errors:0 dropped:0 overruns:0 frame:0
                TX packets:12293 errors:0 dropped:0 overruns:0 carrier:0
                collisions:0 txqueuelen:1000
                RX bytes:14826741 (14.8 MB)  TX bytes:2321884 (2.3 MB)
      
      lo        Link encap:Local Loopback
                inet addr:127.0.0.1  Mask:255.0.0.0
                inet6 addr: ::1/128 Scope:Host
                UP LOOPBACK RUNNING  MTU:65536  Metric:1
                RX packets:20 errors:0 dropped:0 overruns:0 frame:0
                TX packets:20 errors:0 dropped:0 overruns:0 carrier:0
                collisions:0 txqueuelen:1
                RX bytes:2106 (2.1 KB)  TX bytes:2106 (2.1 KB)
      capnkirk@enterprise ~ $ ip a
      1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1
          link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
          inet 127.0.0.1/8 scope host lo
             valid_lft forever preferred_lft forever
          inet6 ::1/128 scope host
             valid_lft forever preferred_lft forever
      2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
          link/ether 30:5a:3a:78:f9:d8 brd ff:ff:ff:ff:ff:ff
          inet 192.168.1.157/24 brd 192.168.1.255 scope global dynamic enp3s0
             valid_lft 85692sec preferred_lft 85692sec
          inet6 fe80::29fe:4469:7af1:2fcb/64 scope link
             valid_lft forever preferred_lft forever
      
      Here's what it looks like when the network is working:
      capnkirk@enterprise ~ $ ping 8.8.8.8
      PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
      64 bytes from 8.8.8.8: icmp_seq=1 ttl=57 time=10.8 ms
      64 bytes from 8.8.8.8: icmp_seq=2 ttl=57 time=11.1 ms
      64 bytes from 8.8.8.8: icmp_seq=3 ttl=57 time=11.2 ms
      64 bytes from 8.8.8.8: icmp_seq=4 ttl=57 time=9.08 ms
      
      This is what it looks like if you can't ping:
      scameron@wombat ~ $ ping 192.168.1.99
      PING 192.168.1.99 (192.168.1.99) 56(84) bytes of data.
      From 192.168.1.157 icmp_seq=1 Destination Host Unreachable
      From 192.168.1.157 icmp_seq=2 Destination Host Unreachable
      From 192.168.1.157 icmp_seq=3 Destination Host Unreachable
      From 192.168.1.157 icmp_seq=4 Destination Host Unreachable
      

      Try pinging 8.8.8.8, which is Google's DNS server. If you are trying to run SNIS on a private network without access to the internet (if you cannot successfully ping 8.8.8.8), and you are able to ping other machines on your network, then special action is required to make SNIS work. Let's say all the machines on your network have an IP address like 192.168.1.xxx. When you start snis_launcher, you should do it like so:

      	export SSGL_PRIMARY_IP_ADDR_PROBE=192.168.1.1
      	./snis_launcher
      

      IPv6. SNIS does not yet work with IPv6. Feel free to send patches.

    • Latency and Bandwidth related problems

      Space Nerds in Space is designed to be run on a LAN, not over the internet. Generally on a LAN, you shouldn't have too much trouble, provided you have a wired network and not a wireless network.

      You can monitor graphs of bandwidth usage and latency on the DEMON screen (press the NET STATS button).

      That being said, there are several variables that are tweakable via the DEMON screen which you can use to reduce the bandwidth requirements and potentially improve latency. (note: use the "vars" command on the DEMON screen to see a list of tweakable variables and their minimum, maximum, and default values).

      1. BANDWIDTH_THROTTLE_DISTANCE: this is the distance below which updated values may not be transmitted to player consoles. Far away objects do not need to have super accurate values reflected in player consoles, so not updating them when they are far away saves bandwidth. Reducing this distance to the minimum will save the most bandwidth at the cost that some things may move around a bit weirdly, esp. at high zoom levels.
      2. DISTANT_UPDATE_PERIOD: For distant objects, updates are throttled and sent only so often. This value controls how often. By default, it is every 2 seconds (20 ticks). Increasing this value to the maximum will save more bandwidth by sending updates for distant objects even less frequently.
      3. NPC_SHIP_COUNT: This is the number of NPC ships generated when the universe is generated. By default it is 250. Reducing this drastically (e.g. say to 20) will drastically reduce bandwidth requirements. This only has an effect when generating the universe, so after setting this, use the REGENERATE command to regenerate a new universe.
      4. ASTEROID_COUNT: This is the number of asteroids generated when the universe is generated. By default it is 200. Reducing this drastically (e.g. say to 20) will drastically reduce bandwidth requirements. This only has an effect when generating the universe, so after setting this, use the REGENERATE command to regenerate a new universe.
      Note, adjusting ASTEROID_COUNT and NPC_SHIP_COUNT generally will not help when running Lua scripted scenarios as such scenarios typically do not use the procedural generation code used by the REGENERATE command when populating the universe but instead typically use their own custom code or a pre-set configuration when populating the initial conditions.

  • Playing over the internet

    Space Nerds in Space was designed to be played on a LAN, not over the internet. I do not recommend playing over the internet. Be aware that the protocol is not encrypted in any way and is not secure.

    Some people insist on attempting it anyway.

    You can control the port that the lobby server runs on via the environment variable via the "Options" menu item of the snis_launcher script or via the environment variable SSGL_PORT. For snis_client, the lobby port number may be entered via the "Options" menu of the snis_launcher script, via the SSGL_PORT environment variable, or via the UI on the network setup screen.

    You can control the range of ports which snis_server will use via the "Options" menu of the snis_launcher script or via the environment variable SNIS_SERVER_PORT_RANGE, e.g. "export SNIS_SERVER_PORT_RANGE=32000:32100". You might want to do this to limit what ports you need to open up on your firewall.

    See doc/running-in-the-cloud.txt for more information.









    Lua Scripting

    Space Nerds In Space has a Lua scripting API to allow you to create mission scripts. This API is described in lua-api.txt. Additionally, the game comes with a few scripts which you can take a look at to get some ideas in share/snis/luascripts. The best examples are:

    Additionally, have a look at MAINMENU.LUA to see how you can tie them all together with a menu system.

    Here are a few video tutorials explaining how to use Lua to create mission scripts:

    • Part 1:
    • Part 2:
    • Part 3:
    • Part 4:

    Miscellaneous Development Topics

    • Why aren't there binaries? Why do I have to compile it myself?

      I will let Linus Torvalds explain why:

    • What about installing the game? The above instructions for building the game have you download the source, compile it, then run it right where you compiled it. What if you want to install it on your system?

      One reason you might not want to install the game is that the game changes quite frequently, and if the protocol changes (as it does) the version you installed is likely to be out of date and you will have to recompile anyway. So "git pull" followed by "make" is not that hard.

      That being said, maybe you do insist on wanting to try installing the game in the traditional sense. I would advise against this (see below), but if you insist, here's how to install the game into /usr/local:

      • make mostly-clean
      • make DESTDIR= PREFIX=/usr/local
      • make DESTDIR= PREFIX=/usr/local update-assets
      • sudo make DESTDIR= PREFIX=/usr/local install
      • sudo make DESTDIR= PREFIX=/usr/lcoal install-assets

      Note that DESTDIR is . by default, so you must specify DESTDIR= if you want it to really land in /usr/local.

      Then you can run it via:

      /usr/local/bin/snis_launcher

      Note that I don't use make install very much, so it's quite possible there are some bugs in the Makefile around this area, though it worked as of Jan 16, 2019, so far as I know.

      If you do want to use make install, there's no reason to do so as root if you pick a PREFIX that you have permission to write into. The main rationale for installing things as root is to put them into, e.g. /usr/local/ and the main rationale for doing that is so that multiple users on the same system can run the program while installing it only once. These days, while linux is a multiuser system, the nature of this game requires that each player have their own computer, and since the game uses OpenGL, you're not going to log in remotely and try to run the game with X windows over the network, so there's no good reason to make install as root.

      Also, snis_launcher will be installed in the bin subdirectory rather than at the top level, so to run it, do: cd $HOME/snis ; bin/snis_launcher.

    • If you want to hack on the game, have a look at CONTRIBUTING.md, and for more details about how to find what bit of functionality is controlled by which bit of code, have a look at Hacking On Space Nerds In Space.
    • Here is a youtube playlist of development videos for Space Nerds In Space spanning the time from the very beginning when the game was literally not much more than just a bunch of dots on the screen up until the present day.

      Here is a set of slides about speech recognition and natural language processing in Space Nerds In Space.

    • Here is a set of slides from a talk I gave about procedurally generating gas giant planet textures: Procedurally Generating Gas Giant Textures.

      Here are some pictures showing various noise-scales and the effect they have in gaseous-giganticus.

    • Here is a slideshow about the implemenation of planetary rings and shadows cast by and on them in Space Nerds In Space.
    • Here is a slideshow about 'earthlike', which is a program used to generate some of the earthlike planet textures within Space Nerds In Space. (Use arrow keys to navigate the slideshow. And press F11 for full screen.)

      Most of the code is licensed under the GPL v. 2, or at your option, any later version. Some parts of the code have an MIT license. Audio files have various other licenses, typically some variant of a Creative Commons license. I have tried to be diligent about making sure it is clear which parts of the code have what licenses. Consult the source if in doubt.

    • Here are some notes about creating Arduino based physical control panels for Space Nerds in Space.
    • Here are some very old out-of-date instructions about creating bootable images to play the game.
    • Here is a copy of the freegamdev.net thread about this game (just a backup in case some disaster strikes that forum)