Windows Git 1.3.5
(Windows Glk 1.50)

Windows Git is an interpreter for Glulx games. Windows Git consists of a core interpreter called Git, and an input/output library, called Windows Glk. Together these two components form the Windows Git package, which has been created by David Kinder.
Web: http://www.davidkinder.co.uk/
Email: davidk@davidkinder.co.uk

Git's main goal in life is to be fast. It's about five times faster than Glulxe, and about twice as fast as Frotz (using the same Inform source compiled for the Z-machine). It also tries to be reasonably careful with memory: it's possible to trade speed off against memory by changing the sizes of Git's internal buffers. Git was written so that people would be able to write huge games or try out complicated algorithms without worrying about how fast their games are going to run.

The latest release of Windows Git is available from the Git page at the IF Archive, which also contains many games that can be played with Windows Git. For help on how to get started with Windows Git, click here.

Windows Git supports all the features of the Glk and Blorb specifications, including graphics (with alpha blending and gamma correction) and sound (as either samples or music). Windows Git is based on Windows Glk by David Kinder and Git by Iain Merrick. Windows Glk and Git are released under these licenses.


Getting Started

In order to use Windows Git, you will need a Glulx game file to play on it. This format was invented by Andrew Plotkin to address the limitations of the widely used Z-code format (also referred to as the Z-Machine), which was originally invented by Infocom, Inc. for the games they released during the 1980s.

Members of the current interactive fiction community have written many games using Graham Nelson's compiler Inform. Inform can produce as output either Z-code or Glulx game files. Glulx games can be downloaded from the IF Archive at
http://www.ifarchive.org/indexes/if-archiveXgamesXglulx.html

When Windows Git is first started, a file dialog opens, prompting you for a game file to load. This file can be either a Glulx file or a Blorb file. A Glulx file has a name ending with .ulx. A Blorb file contains multimedia resources for games, and can also contain the Glulx game as well. Blorb files have a name ending with .blb, .blorb, .glb or .gblorb.

Once a game file is selected, Windows Git will open its main window and start running the game. If the game is packaged with an iFiction record, then the cover art and description is shown first.

Further information:

  • Menus and the toolbar
  • Editing keys
  • Changing options


Menus and the Toolbar

Windows Git provides the following menu items, the most commonly used of which also appear on the toolbar:

Scrollback Ctrl+L
Opens the scrollback dialog, which shows all the text printed since the current game was started.

Options...
Opens the options dialog.

Help
Opens this help window.

About This Game
Opens a dialog showing the cover art and description of the game, if available.

About Git
Opens the About dialog, which shows the version number and credits for this version of Windows Git.

Exit Alt+F4
Exits the interpreter.


Editing Keys

When Windows Git is waiting for input from the user, the following keys have special meanings:
Delete | Delete the character under the cursor.
Backspace | Delete the character to the left of the cursor.
Home | Move the cursor to the start of the input line.
End | Move the cursor to the end of the input line.
Cursor Left | Move the cursor to the left.
Cursor Right | Move the cursor to the right.
Cursor Up | Show the previous input in the input history.
Cursor Down | Show the next input in the input history.
Ctrl+Cursor Left | Move the cursor to the start of the current word, or the previous word if already at the start of a word.
Ctrl+Cursor Right | Move the cursor to the end of the current word, or the next word if already at the end of a word.
Tab | Move the input focus to the next window which is waiting for input.
Shift+Tab | Move the input focus to the previous window which is waiting for input.
Ctrl+Pause | Halts any speech currently being spoken.
Ctrl+V | Paste the contents of the clipboard into the input line.
Alt+Enter | Toggle full screen mode.

The hotkeys assigned to menu items are given here.


Changing Options

From the Options dialog, you can change the various display options of Windows Git.

General Options

Font
Set the font name and size used by the game.

Fixed width font
Set the font used when the game requests a fixed width font.

Text colour
Set the default text colour.

Background
Set the default background colour.

Hyperlinks
Set the colour of hyperlinks.

Borders between windows
If selected, windows that the game opens in the main interpreter window are surrounded by a standard window border.

Enable menus, toolbars and the status bar
If selected, the interpreter window has a menu bar, a toolbar and a status bar. If not selected, these items are not present. In either case, the options dialog is still always accessible from the system menu (that is, the menu obtained by clicking on the icon in the left corner of the interpreter's title bar).

Style hints override user settings
If selected, style hints set by the game override any style options selected by the user. The style options are described below.

If the game has an iFiction record ...
When Windows Git loads a game that contains an iFiction record, it may show the About This Game dialog. This option determines whether the dialog is never shown, only shown the first time, or shown every time.

Style Options

Note that changing the values discussed below will only affect new windows opened by the game, not any existing ones. Furthermore, if the game overrides any of these settings with style hints, then that particular style will not be editable.

Window
Determines the type of window for which the style is being edited. Text buffer windows are the normal windows in which output appears in the proportional font and the user enters input. Text grid windows always show text in a fixed width font and are used for tasks such as a status bar. Only some of the style options are relevant for text grid windows; the remainder are greyed out.

Style
Determines the particular style being edited.

Indentation
How much a paragraph in this style is indented, in arbitrary units.

Paragraph Indentation
How much the first line of a paragraph in this style is indented, in arbitrary units.

Justification
Whether paragraphs are drawn flush with the left margin, the right margin, both margins, or centered.

Text Size
The size of the text, measured in arbitrary units, relative to the default size chosen by the user.

Text Weight
Whether the text is drawn normally, emphasized, or lightly.

Italic
If selected, text is drawn italicised.

Proportional
If selected, text is drawn using the proportional font. If not selected, the fixed-width font is used instead.

Reverse
If selected, text is drawn reversed, i.e. the background colour is used to draw the text, with the background set to the text colour.

Text Colour
The colour in which the text is drawn in.

Background
The colour in which the background behind the text is drawn.

Speech Options

Windows Glulxe can use Microsoft's Speech Engine to speak text. If it is installed, there is a Speech tab in in the options dialog, containing controls that allow speaking of the game's text to be turned on, and the voice and speed at which it is spoken in to be set.


Glulx

The Glulx specification was written by Andrew Plotkin as an attempt to define a format for interactive fiction games that the Inform compiler could compile to, without the limitations of its original output format, Infocom's Z-Machine.

Windows Git is based on Iain Merrick's Git 1.3.5, which is a complete implementation of version 3.1.2 of the Glulx specification.

More information on Glulx is available from the Glulx web page: http://www.eblong.com/zarf/glulx/


Glk

The Glk specification was written by Andrew Plotkin as an attempt to define a standard input and output interface for general use in IF related projects. Windows Git uses my implementation of Glk, called Windows Glk. Windows Glk is a complete implementation of all the features described in version 0.7.4 of the Glk specification.

The complete Windows Glk package, including developer information, can be downloaded from the IF Archive's Glk implementations page.

More information on Glk is available from the Glk web page: http://www.eblong.com/zarf/glk/
Windows Glk also implements the Gargoyle Glk extensions for text formatting: http://curiousdannii.github.io/if/gargoyle.html


Blorb

The Blorb specification was written by Andrew Plotkin as a way of providing graphics and sound resources for Z-code and Glulx games.

A Blorb file contains all the graphics and sound files needed for a game. It can also contain the Glulx code for the game as well, but does not need to: The game could also be distributed as separate Glulx and Blorb files. If you try to load a Blorb file into Windows Git that does not contain a Glulx game, it will ask you to load the appropriate Glulx file into the interpreter instead.

Blorb files can contain JPEG and PNG graphics files, AIFF sound samples, and MOD and Ogg Vorbis music files. Windows Git supports all of these formats, including transparency, opacity and gamma correction for PNG graphics.

From version 2.0, the Blorb specification also includes iFiction metadata and cover art chunks; Inform 7 can produce Blorb files containing these. If present, Windows Git uses them to determine the title of the game and to populate the About This Game dialog.

More information on Blorb is available from the Blorb web page: http://www.eblong.com/zarf/blorb/


Graphics and Sound

Windows Git can load graphics and sound resources either from within Blorb files or as separate files.

If a Blorb file is loaded into the interpreter, or a Blorb file exists with the same name as the Glulx game file, then graphics and sound resources will be looked for first in that Blorb file.

If Windows Git cannot find a requested resource in the Blorb file (or there is no Blorb file), it will look for a suitably named file in the same directory as the game file. The resource formats currently supported are shown below, along with the filename for which the interpreter will look if the resource is not in the Blorb file (as an example, the filename is for resource number 1):

Format | Type | Example Filename
PNG | image | pic1.png
JPEG | image | pic1.jpg
AIFF | sound | snd1.aif or snd1.aiff
MOD | music | mus1.mod
OGGV | music | mus1.ogg


Configuration Files

Windows Git can load a configuration file with the game that sets various attributes of the interpreter window. The configuration file should have the same name as the game except for an extension of .cfg.

The configuration file is a text file where each line contains a key name, followed by an equals sign, then a value, e.g. WindowBorders=no. Possible keys are:

WindowBorders=[yes/no] | Turns on or off borders between windows.
WindowFrame=[yes/no] | Turns on or off the interpreter window's frame, that is, the title bar and the border around the whole window.
WindowMask=[number] | Uses the given Blorb resource number to set the mask for the window from the graphic. If a particular pixel in the graphic is white then the window is transparent at that point, else it is opaque. This key only takes effect if "WindowFrame=no".
WindowWidth=[width] | Sets the width of the interpreter's window so that a single, full-size Glk window will have a width of the given value.
WindowHeight=[height] | Sets the height of the interpreter's window so that a single, full-size Glk window will have a height of the given value.
FullScreen=[yes/no] | If set to "yes", the interpreter's window opens filling the entire screen.
FontName=[font] | Sets the font used for proportional text to the given font name, e.g. Times New Roman.
FixedFontName=[font] | Sets the font used for fixed width text to the given font name.
FontSize=[size] | Sets the size of the fonts to the given value, measured in points.
FontFile=[filename] | The name of a font file (usually ending in ".ttf") to load fonts from.


Automatic Running

When it comes time to distribute your game, you can package up the interpreter with your game into an archive or installer. But if you want the user to be able to start your game just by clicking on an icon, you can rename Git.exe to the same as the name as your game's Glulx file (apart from the .exe file extension). When the interpreter starts up it first looks for a Blorb file with the same name as the executable, and if one is found, loads and runs it straight away. So, if your game file is Foo.blb and the renamed interpreter executable is Foo.exe, all the user needs to do to run your game is double click on Foo.exe.


The IF Archive

The IF Archive is the central site on the Internet for text adventures and related interpreters, compilers and other tools. The Archive has an unrivalled collection of material relating to text adventures, including something in the region of two thousand games. Formerly at the FTP site ftp.gmd.de, it is now at the web site http://www.ifarchive.org/.

The Archive's main collection of Glulx games is in the games/glulx directory. Another source of Glulx games is the annual IF Competition. As the archive contains many hundreds of games, finding one to play can be daunting: a site that aims to help with this is Mike Roberts' Interactive Fiction Database, which provides information and reviews of games in the IF Archive.


Revision History

Git 1.3.5 (Windows Glk 1.50)
  • Support for high DPI and changing DPI with Windows 10: if the DPI is changed (from the Display settings app, or by moving the window from one monitor to another with a different DPI) then the interpreter rescales itself appropriately.
  • The choice of font and font size has been moved to the options dialog. As a result there is now only one font size, which is used for both proportional and fixed width fonts. (This is also true of configuration files: "FixedFontSize" now has no effect in such files.)
  • The toolbar images have been redrawn for a more modern look.
  • Added a Russian translation of the UI by Nikita Tseykovets.
Git 1.3.5 (Windows Glk 1.49)
  • Fixed a bug where attempting to play a MOD sound when one was already playing stopped the already playing one, contrary to the Glk specification: now the attempt to play a second MOD sound fails.
Git 1.3.5 (Windows Glk 1.48)
  • Added support for the Gargoyle Glk extension functions that allow text formatting to be changed dynamically, beyond what is allowed by the standard Glk style model.
Git 1.3.5 (Windows Glk 1.47)
  • Updated to support Glk 0.7.5, which adds character input to graphics windows, clarifies the behaviour of zero-size windows, and specifies the encoding of Unicode text files as UTF-8.
Git 1.3.5 (Windows Glk 1.46)
  • Fixed a bug when the streamnum opcode is called with the smallest possible negative number.
  • A new configuration file option, "FontFile", allows the game's font to be loaded from a font file in the same directory as the game.
  • Some of the Unicode characters above $1000 (that is, those in the Supplementary Multilingual Plane) can now be output, provided that an appropriate font is available.
  • Unicode text files are now encoded as UTF-8, as specified in the latest draft of the Glk 0.7.5 specification.
Git 1.3.4 (Windows Glk 1.45)
  • Performance improvements from Peter De Wachter, which give approximately a 15% speed increase.
Git 1.3.3 (Windows Glk 1.45)
  • The way in which colours are specified in the options dialog has been simplified: the "General" tab now contains three buttons that allow the overall text, background and hyperlink colours to be specified. Text and background colours are no longer specified in the "Styles" tab on a per-style basis.
  • The function glk_window_get_arrangement() no longer causes a crash if any of its output arguments are 0.
  • Added acceleration functions 8 through 13, which work correctly when the Inform 6 compiler setting NUM_ATTR_BYTES is changed, contributed by Andrew Plotkin.
Git 1.3.2 (Windows Glk 1.44)
  • A further fix related to Glk call dispatching, following the similar fix added to Glulxe 0.5.1.
  • Increased the undo buffer size to 2Mb.
Git 1.3.1 (Windows Glk 1.44)
  • Further fixes related to Glk call dispatching, following similar fixes added to Glulxe 0.5.0.
Git 1.3.0 (Windows Glk 1.44)
  • Updated to Git 1.3.0, which fixes a bug related to Glk call dispatching, and a bug in the file restore logic.
  • Updated to support Glk 0.7.4, which introduces resource streams (i.e. access to read-only data held in the Blorb game file).
Git 1.2.9 (Windows Glk 1.43)
  • Updated to support Glk 0.7.3, which includes more control when playing sounds. This revision of the Glk specification also now specifies the meaning of the volume argument to sound related Glk calls: as a result the handling of the volume has been changed to match the specification.
  • [More] prompts now function even if the game has exited, allowing any long amount of final text to be read.
  • Fixed a bug with file streams when reading and writing to the same file.
  • Updated to Git 1.2.9, which fixes bugs related to Glk call dispatching, following similar fixes in Glulxe.
Git 1.2.8 (Windows Glk 1.42)
  • The accuracy of the time returned by glk_current_time() has been improved. Providing that the computer supports a sufficiently high resolution timer, the returned time is now correct to the nearest microsecond.
Git 1.2.8 (Windows Glk 1.41)
  • Updated to support Glk 0.7.2, which includes functions for accessing the system's date and time.
  • Updated to support Glk 0.7.1, which includes functions for Unicode string decomposition and normalization, and control over line input echoing and terminator characters.
  • Unicode characters now appear correctly in the scrollback dialog, provided that the dialog font supports them.
Git 1.2.8 (Windows Glk 1.40)
  • Updated to Git 1.2.8, which fixes a few obscure bugs.
  • Corrected problems with formatting and line input when margin images are present.
  • Corrected a mistake in the handling of alpha-blended images.
Git 1.2.7 (Windows Glk 1.39)
  • Updated to Git 1.2.7, which implements the Glulx 3.1.2 specification (for floating point opcodes).
  • The window can be made to fill the entire screen; press Alt+Enter to toggle this full screen mode on and off.
  • A new configuration file option, "FullScreen", also makes the window fill the entire screen.
  • During line input, Ctrl+Left moves the cursor to the start of the current word, and Ctrl+Right moves to the end.
  • The logic when scaling alpha-blended images has been improved, so there should no longer be artifacts round the edges of such images.
  • Data being written to files is now flushed whenever input is requested from the user. This allows, for example, transcript files to update as a game is being played, and not only when the interpreter closes the file.
  • Corrected a problem which could result in the options dialog using the wrong font.
Git 1.2.6 (Windows Glk 1.38)
  • Fixed a file creation bug in glk_stream_open_file().
Git 1.2.6 (Windows Glk 1.37)
  • Updated to Git 1.2.6, which fixes a bug in retained Glk array handling.
Git 1.2.5 (Windows Glk 1.37)
  • Updated to Git 1.2.5, which fixes several problems shown by Andrew Plotkin's glulxercise test cases.
Git 1.2.4 (Windows Glk 1.37)
  • Clicking on a Glk window now only shifts the keyboard input focus to that window if the window is capable of text input: this means that after clicking on a graphics window, text can still be input in a text buffer window without having to click back to the text buffer window.
  • The implementation of the algorithm for scaling images has been sped up again.


Credits and Licenses

Windows Git package by David Kinder.
Windows Glk is copyright 1998-2019 by David Kinder.
Git is copyright 2003 by Iain Merrick.

License

Both Git and Windows Glk are released under the terms of the MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Git Credits

Iain's text file with the Git source code includes the following credits:

Andrew Plotkin invented Glulx, so obviously Git wouldn't exist without him. I also reused some code from his Glulxe interpreter (glkop.c and search.c), which saved me a lot of time and let me concentrate on the more interesting stuff.

Many thanks are due to John Cater, who not only persuaded me to use source control, but let me use his own CVS server. John also provided lots of useful advice and encouragement, as did Sean Barrett.

Thanks also to Joe Mason, Adam Thornton, Simon Baldwin and Joonas Pihlaja who were among the first to try it out and complain that it wasn't working. Joonas also gets special brownie points for trying out more bizarre boundary cases than I realised existed in the first place.

Tor Andersson was apparently the first person to use setmemsize, since he also explained why it didn't work and contributed a fix. Thanks, Tor!

David Kinder has done a stellar job of maintaining the code recently. Thanks also to Eliuk Blau for tracking down bugs in the memory management opcodes.

Windows Glk Credits

The user interface for Windows Glk has been translated into Spanish by Javier San José, into Italian by Tommaso Caldarola, and into Russian by Nikita Tseykovets.

Windows Glk contains bitmap scaling code written by Eran Yariv. The code that handles Ogg Vorbis music resources is based on code submitted by David Moreno.

Windows Glk uses the following libraries:

  • jpeglib by the Independent JPEG Group.
  • libpng by Guy Eric Schalnat, Andreas Dilger, Glenn Randers-Pehrson, and others.
  • zlib by Jean-loup Gailly and Mark Adler.
  • libogg and libvorbis by the Xiph.org Foundation. (Click here for the license.)
  • MODPlug by Olivier Lapicque.


Ogg Vorbis License

Copyright (c) 2002, Xiph.org Foundation

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

- Neither the name of the Xiph.org Foundation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.