Getting Started

Aika edited this page Jul 3, 2018 · 8 revisions

Here we describe how to get to the point where you have a working cloned repository on your machine that is successfully compiling.

Windows

Installing Inform 7

Download Inform7 and install it. NB you must install the 6G60 one I've linked, NOT the latest version of the compiler which has major changes which will cause TQ and some of its core extensions to fail to compile.

http://inform7.com/download/content/6G60/I7_6G60_Windows.exe

Installing GitHub Desktop

The new version is available at https://desktop.github.com; I've not used it properly myself as I prefer the old version.

Forking the Repository

You don't have permission to make changes to my version of the repository so you need to make your own "fork". On the top right of every page of this GitHub repo there is a fork button next to Watch and Star. Click on that.

Cloning the Repository

It is recommended to clone to C:\Users\[user]\Documents\Inform\Projects\

WARNING if it is not obvious, when you do this, GitHub Desktop will download all the project files to your machine. Consider how confidential your user's Documents space is and also your nation's laws on not-heterosexual and/or niche erotica and so on before you go through with this.

Old Version of GitHub Desktop

In GitHub Desktop after logging in, click the "+" in the top left, and then go to "Clone". Click on "TrapQuest". A button appears below saying "Clone Source", click on it. Browse to the directory above and confirm.

New Version of GitHub Desktop

In GitHub Desktop after logging in, click on Clone a repository (the rightmost of the three buttons). Click on the URL tab. Enter [your-username]/TrapQuest in the top box. Obviously substitute [your-username] for your GitHub username. Click choose next to the local path box and browse to the location you are cloning to and click Select Folder (remember it's recommended to use C:\Users\[user]\Documents\Inform\Projects\). Click the blue Clone button.

Creating the Symbolic Link

Inform 7.exe is really clever and only checks two hardcoded directories for Extensions. One is the default in-built extensions and these are kept in the program files directory. The one for third party directories is C:\Users\[user]\Documents\Inform\Extensions\ and this is where we'll need to make sure that the Inform 7 program can find all our files. To do this we create a symbolic link from that directory to where the extensions are actually kept, inside the repository. So, delete the unnecessary Extensions folder in C:\Users\[user]\Documents\Inform\, open up a command prompt in that directory and use the command below, substituting [user] for your username. NB I've kept the document location that I ran the command from; remove everything up to and including the > if you're trying to copy+paste the command. And remember to substitute in your username.

C:\Users\[user]\Documents\Inform>mklink /D Extensions "C:\Users\[user]\Documents\Inform\Projects\TrapQuest\Trap Quest.inform\Inform\Extensions"

Selkie notes:

If you're using Windows10, you won't be allowed to make the link as an ordinary user: you need to do the fiddly bring-up-the-option-to-run-the-command-shell thing, but instead of running it, right click on it and choose "Run as Administrator". (Selkie finds it amusing that Microsoft's security model is so poor that instead of basing this on the permissions of the folders or files you're linking - as it is in Unix - instead, it's some mystical "Oh, you have to be an Administrator to create a link" mindset. Er... does Selkie talk about herself in the 3rd person a lot? No, she doesn't!)

Where was I? Ah, right. So, as Aika said, from inside that command window (run as Administrator), change into the directory where you have your default Inform documents. That's probably C:\Users\%USERNAME%\Documents\Inform. Let's also assume you have NOT put your Inform projects under "C:\Users\%USERNAME%\Documents\Inform\Projects", but here, say: "D:\games\Inform7\Projs\".

In that case, you would do this:

set MyI7Stuff=D:\games\Inform7\Projs

or

set MyI7Stuff=C:\Users\%USERNAME%\Documents\Inform\Projects\TrapQuestDevelopers

Then:

cd C:\Users\%USERNAME%\Documents\Inform

rename Extensions Extensions.original

mklink /D Extensions "%MyI7Stuff%\Trap Quest.inform\Inform\Extensions"

Compiling

Open Inform 7 from the Start menu. Select 'Open an Existing Project' and browse to C:\Users\[user]\Documents\Inform\Projects\TrapQuest\ to select the Trap Quest.inform directory (this is what it's looking for) and open that.

On the "Settings" tab (on either side - there are two identical window panes), select "Glulx" for the target.

Click the big 'Go!' button to start compiling. This will be a rather CPU-intensive task that lasts for 5 to 30 minutes depending on your processor. Time for a coffee.

Troubleshooting compilation

If you can now see the first Trap Quest menu (with 'restore a save file' at the top) on the right hand side of the window, congratulations you have successfully compiled and now the game is running inside Inform 7's internal interpreter. This interpreter is super slow so you'll not enjoy playing the game in this but it works for testing and doesn't get upset at missing images which is great.

Here are some other things you might see instead and the issues that usually cause them.

  • 'Fatal error' at the bottom of the menu, and the game is unresponsive.
    • This usually means that you have resized the window while the game was on a menu screen. This can also occasionally happen if the window is left untouched and inactive for ages and then you return to it, because the window is sort-of 'resized' as Windows reloads it into active memory.
  • Inform failed to package up the compiled source because of missing images.
    • You tried to 'Release' the game rather than just compile ('Play').
  • Complains about extensions being made for 'glulx only'
    • You didn't go to the settings tab and change the compiler to glulx
  • Compiler finishes instantly with a compile error saying that Extension files are missing.
    • You didn't successfully make the correct symbolic link.
  • Compiler finishes within 1 or 2 minutes with a compile error
    • Very unusual, this probably means that the current 'master' branch version has a bug in it that prevents compilation. This happens when someone makes what they think is a 'quick fix' without testing it before making a pull request and it doesn't get caught by Aika before the pull request is merged. Poke Aika and let them know.
  • Internal interpreter dies while loading the Dungeon region
    • The game already compiled successfully so you're in the wrong section. You should have read the 'development tips and tricks' page before testing, where this problem is explained.

Syncing your Fork

At some point you'll need to sync your fork with the base code, when I've updated the repository. To do this...

Old GitHub Desktop

TODO

New GitHub Desktop

  • Make sure you're in your master branch.
  • Click Branch (at the top) > Merge into current branch... > upstream/master
    • If you just cloned your fork really recently, it might not have upstream/master here yet because it only syncs periodically. Check back soon.
  • Click the blue Merge into master button.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.