Home

This page provides a general overview of using JSILc.

For information on how to configure JSILc, see Configuration Files. For information on the XNA Content Project support, see XNA Profiles.

1.) Obtaining Source Code

The first step in running JSIL is to obtain the source code. Since you're on github already, it is assumed that you have a basic understanding of git.

First let's clone the JSIL repo:

git clone https://github.com/kevingadd/JSIL.git

Now, let's grab all the submodules:

cd JSIL
git submodule update --init

You should now have all the source code necessary to be able to run JSIL! Congrats.

Note that, if you ever need to update your local copy of the source code, you can:

git pull --all
git submodule foreach git pull origin master

2.) Building and Running JSIL

Now that you have the source code, open JSIL.sln with Microsoft Visual C# 2010 (Express is fine). Press F6 to build all projects in the solution. Hopefully this will work for you without errors, if you pulled the source code properly. If you receive errors regarding stuff like "XNA", you likely need to install the appropriate version of XNA. If the build succeeded, you should see a message on the bottom left stating so. Also your output window will say something like this:

========== Build: 11 succeeded or up-to-date, 0 failed, 0 skipped ==========

If anything ends up failing, you should resolve those because JSIL will likely not work as intended. If anything is skipped, you may need to change your build configuration defaults in Visual Studios (Build->Configuration Manager). For some build configurations, it will say you are trying to run an older version of a library. This is generally OK but resolving this could save you some headaches.

If everything is working as intended, pressing F5 to run JSIL will bring up a command prompt window, send some text through, and then close without an error. Example in output window: (obviously your process ID will likely be different)

The program '[4552] JSILc.vshost.exe: Managed (v4.0.30319)' has exited with code 0 (0x0).

Next step, you can test this with your own C# XNA project. In command prompt, change directory to the path/to/JSIL/bin filepath, and execute this: (replacing path/to/YOUR_FILENAME.exe with your respective compiled C# XNA executable)

JSILc.exe "path/to/YOUR_FILENAME.exe"

You can alternately invoke JSILc with the path to a Visual Studio solution file, and it will attempt to build the solution and translate its output(s):

JSILc.exe "path/to/YOUR_FILENAME.sln"

Assuming nothing errors out, JSILc will load up your assemblies and their dependencies, translate them to javascript, and generate .js files in the current directory. We will use these javascript files to be able to run your program in a web browser.

What if you want to test this quickly and rapidly from inside Visual Studio, without command prompt?

Go to Visual Studios; Right Click "Compiler" in the solution explorer, and click Properties. Click the Debug tab. You will see a textbox labelled "Command line arguments". Type in your filepath here (as demonstrated above). Save, and hit F5. JSIL should have ran, using the filepath you just provided as its first argument.

3.) Using the compiled javascript in a webpage

(This section is currently under construction, so consider it an information dump until it is completed and organized.)

It is currently advised to run your compiled javascript using the scaffolding of the examples hosted on JSIL.org, such as the xna3.1 platformer.

Include

<script src="../Libraries/JSIL.Core.js" type="text/javascript"></script> 
<script src="../Libraries/JSIL.Bootstrap.js" type="text/javascript"></script>
<script src="../Libraries/JSIL.Browser.js" type="text/javascript"></script>  

By default (if you use the platformer scaffolding), JSIL looks for its libraries (marked Library) at "../Libraries/" (the variable used is libraryRoot). JSIL looks for your custom/compiled scripts (marked Script) at "" (the variable used is scriptRoot). JSIL looks for anything marked File at "" (the variable used is fileRoot). JSIL looks for your content (marked Image, Sound, Font ...) at "Content/" (the variable used is contentRoot). Currently, you must provide the uncompiled version of all content (raw format, like png, mp3, ttf).

All script files that were created by loading your program into JSILc.exe should be included in the variable, assetsToLoad.

In order to properly get your compiled javascript code to run, you must call your main function in javascript.

  function runMain () {
    try {
      document.getElementById("welcomeMessage").setAttribute("style", "display: none");
    } catch (ex) {
    }
    $asm01.MyNameSpace.Program.Main([]);
  };

Replace MyNameSpace.Program.Main with the path to your main function. For XNA games, you'll want to create an instance of the Game object and call Run instead, because the main function will immediately exit (it relies on a Windows Forms message pump, and those are impossible to implement in JS.)

TO BE CONTINUED

4.) Handling javascript errors (those pesky exceptions!)

...