Smart Game Format (SGF)

Items listed in the Archive area of the app (see The game archive) are games saved in the Smart Game Format, which is generally abbreviated to SGF. The format is decades old and widely used to store and transfer Go games between computer systems. External link to SGF specification.

The app internally uses a software package named SGFC (the SGF Syntax Checker & Converter) to load and save SGF data. External link to SGFC website.

This page describes the technical details how the app uses SGFC to process SGF data, and the settings you can change to influence the processing.

Behind every item that is listed in the Archive area of the app (see The game archive) there is one SGF file. Tapping the archive item loads the SGF file’s content and puts it through SGFC to parse the SGF data. Whenever SGFC finds something suspicious or wrong in the data it generates a message. It does this separately for each issue it finds, so that in the end parsing the data of a single SGF file can result in many different messages.

Messages are classified with two criteria: Message type and message criticality.

Message types in ascending order of severity are:

• Warning
• Error
• Fatal Error

Warnings and errors still allow the SGF data to be parsed, but a fatal error generally means the SGF data is broken in some fundamental way and cannot be parsed.

A warning or error message can be critical or non-critial. Fatal errors are neither critical nor non-critical - they are, well, fatal.

A critical warning or error message indicates that the SGF data may be severely damaged.

A critical warning is more severe than a non-critical error.

You see SGFC messages when you tap an archive item and the app displays the “View archive content” screen. See the Game archive page for details how the screen looks like.

Near the top of the screen is a section titled “Load result”. This shows you at a glance a summary of the messages generated by SGFC when it parsed the SGF data.

Ideally the load result is “0 warnings, 0 errors”, which means that SGFC did not find any issues with the SGF data.

If the load result is anything else than “0 warnings, 0 errors” then you can tap the load result summary item to see the actual list of messages that were generated by SGFC.

If you wish you can even drill down into an individual message to see the low-level data of which the message consists. This can be interesting because most messages contain the actual line and column number where SGFC found the issue in the SGF file.

SGFC is very strict and generates many messages when it finds SGF data that does not conform to the SGF standard. As long as you load only SGF files from the archive that you have saved in the app you will be fine and see no messages (i.e. you will see the “0 warnings, 0 errors” load result), because the app strictly adheres to the SGF standard. When you import SGF files from external sources, though, you may start to see some messages from SGFC that complain about various things in the SGF data that are not correct. The reason is simple: Not all applications that generate SGF data adhere as strictly to the SGF standard as they should.

To let you deal with situations where you are unable to load an SGF file from an external source, the app offers various settings that influence the way how SGF data is processed when you load a game from the archive. The next sections on this page discuss the details of these settings.

You find the settings in the Settings area of the app under “Smart Game Format (SGF)”.

The SGF syntax checking settings define how strict SGFC should be when it checks an SGF file’s conformity to the standard, which warning and/or error messages SGFC should not generate even if it detects a problem, and what kinds of warning and/or error messages may be present for the app to still accept SGF data and load it.

The simplest way to change the SGF syntax checking settings is to select from a number of syntax checking levels.

In general, levels range from less syntax checking to more syntax checking. Each level represents a different set of predefined settings values. By selecting a syntax checking level you are effectively changing several settings with a single tap, without having to understand what the individual settings do.

Individual syntax checking settings are also open to manual tweaking. To do so, tap the “Advanced configuration” item in the syntax checking section of the SGF settings screen. Before you start changing things, however, it is probably a good idea to first read through the next sections so that you better understand what you can accomplish by manipulating each setting.

The default (and recommended) syntax checking level is Medium. It strikes a balance between indicating almost all SGFC messages (except some of the most common and trivial warnings) and still allowing most SGF files to be loaded (except those with critical SGFC messages).

The following table shows how each syntax checking level maps to the individual settings.

This setting defines what kinds of warning and/or error messages may be present for the app to still accept SGF data and load it.

When you tap an archive item and the currently selected load success type causes the loading of SGF data to fail you will see an item “No games available”. Below that item there is a “Force loading” button that you can tap to override the app’s decision to not load the SGF data.

Fatal errors always cause the loading of SGF data to fail. SGF data with a fatal error cannot be force-loaded because it is broken in some fundamental way and cannot be parsed.

This setting, if enabled, makes SGF data parsing even more pedantic than usual. More warnings and errors are generated, and in some cases messages that were already generated without this setting are now promoted in severity (e.g. warnings may become errors).

This setting is designed to flag all kinds of bad style or uncommon characteristics in SGF data. Because it makes it more difficult to load SGF data it is mostly intended for those users who are curious to see if SGF data they obtained from an external source is well-formed.

Turning on this setting causes all warnings (both critical and non-critical) to be disabled, meaning they are not generated in the first place. This setting has two main uses:

• Conveniently get rid of many annoying messages with a single tap.
• Get rid of one or more critical warnings that prevent SGF data from being loaded. Note that you can also achieve this by manipulating the Load success type setting.

This setting is somewhat dangerous as it blanks out many useful messages and even avoids warnings that are indicators for critical problems in the SGF data. Therefore enable this option only with care!

This setting lets you disable specific warning and/or error messages (both critical and non-critical). Messages are identified by their number. You disable a specific message simply by adding its ID number to the list.

Unlike the Disable all warning messages setting which blankets out all warning messages indiscriminately, this setting gives you more precision, but on the other hand it’s more work to maintain the list. If you want to read up on the possible messages, their ID numbers and what their meaning is, you can consult the SGFC documentation (external link).

The app curates a short list of messages that are disabled by default. Here is the list with the reasons why the messages are disabled:

Because Go is played in many countries all over the world the handling of text encodings is of particular importance when reading and interpreting SGF data, An SGF data processing application such as Little Go cannot make the assumption that the SGF data it processes consists of only ASCII data - to the contrary, when the SGF data originates in Asian countries it is almost guaranteed that the data will contain multi-byte character sets such as Traditional or Simplified Chinese, the Korean alphabet Hangul, or a form of the Japanese writing system.

For this reason the app provides a number of rather technical settings that let the user control all aspects of text encoding handling that are supported by SGFC.

This setting defines how the text encoding should be determined with which to interpret SGF data when it is loaded.

The “Single encoding” mode has the special property that it allows SGF data to be read that begins with a Unicode byte-order mark (BOM). If a BOM is found the BOM instead of the first CA property determines the text encoding to use. This is the ONLY way how UTF-16 or UTF-32 encoded SGF data can be loaded.

This setting defines which text encoding to use if the SGF data does not contain a CA property that explicitly specifies the text encoding.

When left blank the default encoding specified by the SGF standard is used, which is ISO-8859-1.

This setting is useful when an SGF file in the archive contains no CA property but the file is encoded with a text encoding that is not ISO-8859-1.

When you enter a text encoding the app checks whether the name you entered is valid and supported on your device. If the check fails the app displays an alert. If the check succeeds the app does not display an alert.

This setting defines which text encoding to use at all times when loading SGF data. This encoding overrides any CA properties that exist in the SGF data.

When left blank no text encoding is enforced.

This setting is useful when an SGF file in the archive contains a CA property that specifies one encoding, but the file is actually encoded with a different encoding. In that case loading of the SGF file will likely fail. If you know the file’s encoding you can enforce it, which will allow you to load the file.

When you enter a text encoding the app checks whether the name you entered is valid and supported on your device. If the check fails the app displays an alert. If the check succeeds the app does not display an alert.

This setting fixes bad style SGF data, where the main line of a game is not in the main branch (variation “A”), but instead is the last variation.

When this setting is turned on variations are reordered when a game is loaded. For instance, A, B, C, D is reordered to D, C, B, A.