HTML5 Anywhere: ShiVa WebGL on localhost – ShiVa Engine

HTML5 Anywhere: ShiVa WebGL on localhost

One of ShiVa's biggest strengths has always been its cross-platform nature. No matter if desktops, mobiles or game consoles, if it exists, chances are that there is a ShiVa engine port for it. And if you are running an OS or processor off the beaten path, you can always try HTML5/WebGL. Web distribution might not be what you had in mind though... Maybe there are ways to make your web application fit for offline distribution!
Since we assume that you are on a platform where no native ShiVa port is available, it is likely that you will be faced with some sort of *nix OS, such as variant of Linux or FreeBSD, running on some exotic hardware. On the software level, those systems are structured all quite similarly and offer similar tools, which make the methods described in this tutorial fairly universal. However, you will still need proper drivers for 3D hardware acceleration on your system, which will be different from platform to platform.

Local file problems

If you have ever tried to open a fresh ShiVa HTML5 export on your hard drive in e.g. Chrome, you will have seen this error message:

Your browser: Mozilla/5.0 (X11; FreeBSD amd64) Chrome/61.0.3163.100 Safari/537.36
is not able to open local files.
Please use Mozilla FireFox for your local development, or use a local web server

The security settings in many browsers make it hard or impossible to run local HTML5/WebGL applications straigt from your hard drive. The error message suggests two solutions. Option one: Use a browser with less security restrictions by default, like Firefox. However this is not very elegant and often simply not practical. Being told which browser to use can be a very annoying thing for your customers. There also might not be a Firefox port on their system, or they might not have permission to install a new browser, which is a common restriction on company computers. In short, while using Firefox might be a good way for developers to test and troubleshoot their applications, it is not a good solution for your customers. Option two: run a local web server. This suggestion sounds intimidating at first, but can actually be done fairly easily in a few different ways. And the best thing is, you may already have everything required on your machine, assuming a fairly standard *nix environment.

Project structure

Going forward, we will assume a project structure where the server files and startup scripts are in their own folder, while the ShiVa HTML5 export resides in a ./data subfolder:

Standalone servers

The first method involves shipping an actual server binary with your project. Of course, re-packaging the whole XAMPP stack would be a bad idea. However, there are several tiny standalone http servers to choose from, including:
- lighttpd: small memory footprint, advanced features, BSD license
- thttpd: quite old, requires a bit of config fiddling
- webfsd: server of choice for this tutorial
Many of these servers might already be available on your system, so you don't even have to compile them from scratch. Simply put the server binary into your project directory. Now we need a starter script, which could look something like this:

  1. #!/bin/sh
  2. # go to the correct path
  3. ScriptTemp=`readlink -f "$0"`
  4. ScriptDir=`dirname "$ScriptTemp"`
  5. cd -- "$ScriptDir"
  6. # run webfsd server
  7. ./webfsd -r "./data" -p 8080
  8. sleep 2
  9. # launch default browser with
  10. xdg-open http://localhost:8080

After changing directory to the server folder, we simply run it with a set web root directory and port, sleep for a bit to make sure it has started, and then launch the default web browser pointing at a localhost address with our port number. If xdg-open is not available on your system, you might have to use the actual browser application binary name.
This method has a disadvantage in that it requires you to recompile the server binary for every platform you intend to run on. Since all of the servers listed above are open source and compile with freely available compilers, this should not be too difficult, however it takes time and requires maintenance.

Server one-liners

Using a tiny server binary was already very easy. However, we can be even more elegant and reduce the local server to a single line of shell script, using the tools and applications that might already come with your system. For instance, did you know you can start a server in nodeJS, set the web root, and open the web browser in a single command?

  1. http-server "./data" -p 8080 -o

Naturally, this requires nodeJS and the http-server module to be installed, as well as their dependencies, which might be the case for well equipped and developer-focused distributions, but far from certain on user systems. However, one scripting language that is virtually guaranteed to be on your *nix system is Python, which has a similar trick up its sleeve:

  1. python3.6 -m http.server 8080

Since the python server is blocking by default, you have to write a startup script like this:

  1. #!/bin/sh
  2. # go to the correct path
  3. ScriptTemp=`readlink -f "$0"`
  4. ScriptDir=`dirname "$ScriptTemp"`
  5. cd -- "$ScriptDir"
  6. cd "./data"
  7. # run python server
  8. python3.6 -m http.server 8080 & pid=$!
  9. sleep 2
  10. # launch default browser with
  11. xdg-open http://localhost:8080

We are using similar techniques as in the webfsd script, however python replaces the dedicated server binary.
Python and nodeJS are only two examples of useful server oneliners. You can do the same with Ruby, Perl, PHP and many more. There is a handy list on github which you should definitely check out if you have a common scripting language installed on your target machine.

  • slackBanner