RealBridge Config Files

This guide is for those who have already seen Running an event. After you have looked here, at this chapter, we recommend that you look at these chapters:


updated 2 July 2023

What is a config file?

A config file (short for "configuration file") is a text file in a specific format. It contains information used by RealBridge about a session. Some of this is information that is available via the RealBridge application; some of it can only be viewed via the config file.

The main purpose is to allow you to run events over multiple sessions. However, the same config-file mechanism can also be used to create more sophisticated or custom configurations that can't be achieved using the RealBridge front-end directly, or to obtain additional information about the format of the event.


Main uses of a config file

Multi-session events

In a multi-session event, a config file is used by RealBridge to carry forward data from one session to the next session:

  • The config file tells the second and subsequent sessions the names of the contestants, where they should sit, and the current scores.
  • In a Round Robin event, the draw is set at the start of the first session. The config file gives each subsequent session the assignments for the remaining rounds.
  • In a Swiss event, the config file tells each subsequent session which contestants have already played each other.
  • In a Howell or Mitchell that is split across sessions, the config file tells each subsequent session where to restart the movement.

If you are simply using a config file as part of a multi-session event, for the transition from one session to the next, you do not need to understand the details of the config file. You can just use the config file, and it will work. For details, see:

https://realbridge.online/how-to-run-multi-session-teams.html
https://realbridge.online/how-to-run-multi-session-pairs.html

Initial configuration

For single-session events (or the first session of a multi-session event), you can use the config file to:

  • Restrict the event to particular players.
  • Pre-assign the starting positions or team numbers.
  • Set the names of teams in advance (but this can also be done, more easily, via the RealBridge application).
  • Specify the draw in a Round Robin.
  • Specify the first-round assignments in a Swiss.

This approach is useful for developers who wish to integrate RealBridge with their own front-end.

If you are creating config files manually, RealBridge recommends that you use this method only when necessary. Creating the config file manually is time-consuming, and it is easy to make a mistake in the configuration

Viewing future assignments

In a Round Robin teams, if you want to know what the future assignments will be, you can generate a config file and view the assignments for the entire event.


Loading and exporting a config file

Config files are loaded and exported from the Advanced menu.

If you are loading a config file, you should do this before you open the session for the players.

When you load a config file, this will overwrite all session settings, advanced settings, tables, team names, carryovers, categories, etc.

In a multi-session event, at the end of each session you must export the config file, before the session is destroyed.  At the beginning of the next session you load the config file. For more details, see:

https://realbridge.online/how-to-run-multi-session-teams.html
https://realbridge.online/how-to-run-multi-session-pairs.html

Before the start of a round robin, you can export a config file so as to find out what the assignments will be. Exporting before the start is only allowed for a round robin session.


Config file examples

(Updates 9/6/2021)

The config file is in JSON format. The following examples demonstrate the use the file. A full list of allowed attributes and values is given later in this document. All components of the config file are case-sensitive.

Example 1: Single round-robin teams

The file will be ready to download in the chatbox in the lobby:

    {
        "num_tables":5,
        "scoring_method":17,
        "vp_scale":2,
        "team_names":["Barcelona","Madrid","Valencia","Seville","Malaga"],
        "use_screens":true,
        "self_alert":true,
        "time_per_round":7800,
        "time_display":0,
        "boards_per_round":16,
        "match_assignments":[
            [ 2, 1, 5, 4, 3],
            [ 3, 4, 1, 2, 5],
            [ 5, 2, 4, 3, 1],
            [ 1, 3, 2, 5, 4],
            [ 4, 5, 3, 1, 2]
        ]
    }
	

Download config file here

Most of the elements are self-explanatory.

scoring_method:17 means round-robin IMP teams.

team_names lists the teams in order of table number, so Barcelona is at Table 1, Madrid is at Table 2, etc.

The match_assignments element works like this:

  • Each row is a round. The first row is round 1, the second row is round 2, etc.
  • Each column is the opponents for a given team. The first column is Team 1’s opponents. The second column is team 2’s opponents, etc.
  • If a team is shown as drawn against themselves, that means that they have a bye.

Hence this should be read as:

  • Round 1: 1 plays 2, 2 plays 1, 3 plays 5, 4 plays 4, 3 plays 5.
    That is: 1 v 2, 3 v 5, 4 has a bye
  • Round 2: 1 plays 3, 2 plays 4, 3 plays 1, 4 plays 2, 5 plays 5.
    That is: 1 v 3, 2 v 4, 5 has a bye
  • etc

For an explanation of the other elements in the config file, see later in this document.

This config file can be used in two ways:

  • Usually you will leave RealBridge to create the assignments. You may want to see what the assignments will be. To do this, immediately before starting the event, export the config file.  The match_assignments will contain the assignments for the entire round robin.
  • If you want to set the assignments yourself, you create a file like this before the event starts, and load it into RealBridge before the start of the first session. Then RealBridge uses your match_assignments data to determine the assignments.

Example 1a: After the first round is over

If you save the config from Example 1 at the end of Round 1, you will see several differences:

  1. The assignments element will have been split:

        "match_assignments":[
                [ 3, 4, 1, 2, 5],
                [ 5, 2, 4, 3, 1],
                [ 1, 3, 2, 5, 4],
                [ 4, 5, 3, 1, 2]
            ]
            "previous_match_assignments":[
                [ 2, 1, 5, 4, 3]
            ]
    		
    

    previous_match_assignments shows the round that has already been played.

    match_assignments shows the rounds that have not yet been played.

    After the second round, the next row from match_assignments would be moved into previous_match_assignments.

  2. The pairs that have played for each team will be listed:

            "co_lineups":[
                {"pairs":["Alan Adams","Brian Birt","0"],["Caren Charles","Danni Downs","1"]},
                {"pairs":["Ed Evans","Frank Fullerton","2"],["George Good","Harriet Howe","3"]}
                {"pairs":["Ive Ince","James Jones","4"],["Karen Knight","Lisa Lowe","5"]}
                {"pairs":["Mike Mill","Norman Nott","6"],["Ophelia Ord","Peter Piper","7"]}
                {"pairs":["Quentin Quick","Richard Rice","8"],["Sara Smith","Tonya Town","9"]},
            ],
    
    

    The first array lists the players in Team 1, the second array lists the players in team 2, etc. If a team has had more than two pairs, all the pairs in the team will be listed.

    If you plan to use the config file in a subsequent session:

      • Do not delete or add any pairs.
      • You can edit a player’s name to correct an error. If the player’s name appears in more than one place, make exactly the same changes to every instance of the player’s name.

     

  3. Score information will have been added, in elements called co_pair, co_pair_den, co_total. Normally you will have no reason to edit or delete this information.

Example 2: Double round-robin teams

To play a double-round robin, we simply add more assignments:

    {
        "num_tables":5,
        "scoring_method":17,
        "vp_scale":2,
        "team_names":["Barcelona","Madrid","Valencia","Seville","Malaga"],
        "use_screens":true,
        "self_alert":true,
        "time_per_round":7800,
        "time_display":0,
        "boards_per_round":16,
        "match_assignments":[
            [ 2, 1, 5, 4, 3],
            [ 3, 4, 1, 2, 5],
            [ 5, 2, 4, 3, 1],
            [ 1, 3, 2, 5, 4],
            [ 4, 5, 3, 1, 2],
            [ 1, 4, 5, 2, 3],
            [ 4, 5, 3, 1, 2],
            [ 5, 3, 2, 4, 1],
            [ 2, 1, 4, 3, 5],
            [ 3, 2, 1, 5, 4]
        ]
    }
	

Download config file here

Note that the second round-robin does not have to be the same as the first round robin.

Example 3: Teams of eight

New documentation here

Example 4: Swiss Teams

For Swiss events, you can specify match assignments for any number of rounds. In particular, you can specify a fixed draw for the first round instead of using the default random draw. Once all specified rounds have been played, RealBridge will create a Swiss draw for each round based on the current scores.

{
  "num_tables": 6,
"scoring_method": 33,
  "team_names": [ "Barcelona", "Madrid", "Valencia", "Seville", "Malaga", "Paris" ],
  "match_assignments": [
    [ 2, 1, 4, 3, 6, 5 ]
  ]
}  

Download config file here

The configuration looks exactly the same, except that the scoring method is 33 (which means Swiss Teams), and you only specify assignments for one round (or you could preassign more than one round if you wanted to).

In this example, 1 plays 4, 2 plays 17, 3 plays 9, 4 plays 1, etc.

Example 4a: Swiss Teams with a triple

With a triple, match_assignments and previous_match_assignments store the triple assignment as:

(team number of opponent 1) + 1000 x (team number of opponent 2) 

eg 6015 means that the team plays in a triple with teams 6 and 15. This could also be encoded as 15006.

In this previous-match-assignments element:

"previous_match_assignments":[
[11002,1011,13,5,4,7,6,12,10,9,2001,8,3]
]

teams 1, 2 and 11 played in a triple

Example 5: Seat assignments in a pairs event

Another customisation possible with the config file is to "reserve seats" by name. When a player logs in with a name that matches a seat reservation, they will automatically be taken to the correct table and seat. (It can be helpful to combine this option with customised links per player, so that their name is encoded in the link parameters - this ensures that the names match.)

Seating assignments are used automatically in multi-session pairs events, to ensure the pairs start in the correct place to continue the movement. They can also be used for a single-session event (or the first session of a multi-session event), using a config file created outside RealBridge.

    {
        "num_tables":2,
        "seat_assignments":[
            {"n":"Alice","s":"Bob","e":"Clare","w":"Doris","table":1},
            {"n":"Ed#87364","s":"Fiona#63840","e":"Geoff Smith#4738f6","w":"Henrietta#783dfd","table":2}
        ]
    }
	

Download config file here

This simple example assigns players to seats assignments for two tables. The first will reserve seats based solely on names, the second with names and ID. A player must log in with their name and ID exactly as in the config file or they will not be able to sit in the seat.

You will see the keys ew_pair and  ns_pair in an exported config file, you do not need to set these, they are assigned internally.

Example 6: Seat assignments in a teams event

In a teams event, you can either use the same "table":n method, or use "team":"team name". If you do this, you must also use a team_names element to define the team-names:

    {
        "num_tables":5,
        "scoring_method":17,
        "vp_scale":2,
        "team_names":["Barcelona","Madrid","Valencia","Seville","Malaga"],
        "seat_assignments":[
            {"n":"Alice","s":"Bob","e":"Clare","w":"Doris","team":"Valencia"},
            {"n":"Ed","s":"Fiona","e":"Geoff","w":"Henrietta","team":"Madrid"}
        ]
    }

Download config file here

Seat assignments are not automatically created in multi-session teams events. This is because a team may want to change its lineup or switch directions.

If you have your own mechanism for teams to submit line-ups for a session, you can create a config file to ensure that players sit in their allotted seats.

Notes about seat assignments

You are not obliged to assign players for every seat, or for every table. For example, this assigns the NS pair at table 2 but leaves EW open:

    {"n":"Ed","s":"Fiona","table":2}

This can be used when you have a sitout, or when you only know about some of the players.

Even if some seats have been preassigned, you can still add tables as normal.

Clicking the "Minus" button will remove missing pairs, even if a pair is preassigned to the seats. This may result in changes to the initial positions of other pairs, as they are moved to fill in the gaps.

If a player logs in with a name that is not assigned to a seat, by default they will arrive in the lobby as normal. They will not be able to sit in a seat that has been pre-assigned. If they should have been preassigned, ask them to log in again, using exactly the same form as the preassigned name. Note that player-names are case-sensitive.

You can prevent unassigned players from logging in by setting the parameter prevent_unreserved_login to true. Note that this only works if there are no seats that have not been assigned a player. If you have a mixture of unassigned and assigned seats, a player will still be able to log in. This is so that, if a player is having trouble logging in with the name you used in the config file, you can remove the assigned name and allow the player to log in.

From the lobby, a pre-assigned seat will initially be shown as occupied, but in pale green to indicate that the player has not yet arrived. When the player logs in, the seat will appear as occupied in the normal colour.

If you want to open a pre-assigned seat to somebody else, use the "kick player to lobby" mechanism to remove the preassignment. Then another player can take that seat from the lobby. In the "kick player to lobby" drop-down, a seat which is reserved but currently empty will appear as "RESERVED", followed by the player’s name.

If a player at a preassigned seat clicks "Leave", he goes to the lobby and the seat becomes vacant.

Example 7: Carryover scores in a teams event

In a teams event, the carryover scores for the teams are in the co_total element. You can use this to pre-assign carryovers:

    {
        "num_tables":5,
        "scoring_method":17,
        "vp_scale":2,
        "team_names":["Barcelona","Madrid","Valencia","Seville","Malaga"],
        "co_total":[ 60.32, 17.82, 38.14, 20.03, 34.22 ]
    }

 

Example 8: Table Announcements

Table announcement documentation is now found here.

Example 9: Categories

    {
       "num_tables": 4,
       "seat_assignments": [
            { "table": 1, "n": "Andy Adams#", "s": "Barry Brown#", "w": "Peter Purbeck#", "e": "Oliver Oswald#" },
            { "table": 2, "n": "Eva Edwards#", "s": "Frances Fielding#", "w": "David Down#", "e": "Charlie Cook#" },
            { "table": 3, "n": "Ian Ince#", "s": "Julia Jones#", "w": "Harry Hughes#", "e": "Gerry Gallagher#" },
            { "table": 4, "n": "Mary Morris#", "s": "Nick Nott#", "w": "Lola Lewis#", "e": "Kevin King#" }
        ],
        "categories": [
          { "name": "Club" }, 
          { "name": "Group", "sort_order": ["Expert", "Tournament", "Advanced"] }
        ],
        "category_data": [
            ["Manchester", "Expert"], 
            ["Bristol", "Tournament"], 
            ["Manchester", "Advanced"], 
            ["Manchester", "Expert"], 
            ["Bristol", "Expert"], 
            ["Edinburgh", "Tournament"], 
            ["Edinburgh", "Advanced"], 
            ["Manchester", "Tournament"]
        ]
    }

The categories element defines the name of each category and the sort order, if required. In this example, there are two categories: "Club" and "Group". The "Group" category has a sort-order specified.

The category_data element sets the category values for each contestant. For each contestant there is an array of category values. In this example, pair 1 has "Club" = "Manchester", "Group" = "Expert".

In a pairs event, there should be one element for each pair, in order of pair number. (If you haven't specified the pair numbers, NS1 is pair 1, EW1 is pair 2, etc.)

In a teams event, there should be one element for each team, in order of team (table number).

To set category values for contestants, you should normally also include the contestants - the pairs in a pairs session (as in the example above), or the team names in a teams session (using the team_names element).


How to create a config file

You can create a config file entirely outside RealBridge. For most types of session, we recommend that you either create a config file containing just a small number of parameters, or start with one of the examples on this page and amend it. Using that approach, you will get a config file containing only the parameters that you actually need, and the config file will be easy to understand and modify. 

Specifically for round-robin events, it may be easier to do some of the work in the RealBridge front-end. This will provide you with a complete round-robin draw for the number of tables you have chosen. The suggested procedure is:

  • Create a new session. This will just be a dummy session.
  • In the session, create the session settings, set the right number of tables, and fill in the names of the teams.
  • Save the config file.
  • Edit the config file in a text editor. We recommend Visual Studio (see below) but you can also use TextPad or NotePad++ for Windows, or TextEdit for Mac, or any text editor (even Notepad).
  • Create a new session (or reboot the one you used earlier). This will be the session you actually use.
  • Load the config file.
  • Check the settings.
  • You can change the session settings at this point.
  • If you included match assignments in the config file, do not change the number of tables.
  • Open the session.

Recommendations

We recommend using Visual Studio Community Edition (Free) to edit config files as there are many features that make it easier to edit. When you install (or modify your current version of Visual Studio) you will need to install the ".NET Desktop Development" package. See how to install Visual Studio and some other useful tips in our video tutorial.

If you prefer a more lightweight program, on Windows use Notepad++. This has a JSTool plugin which provides formatting for JSON.

When editing the config file, it is OK to add spaces and line-endings between the elements, to make the file easier to read and edit.

Remember that when you load a config file, this will overwrite all session settings, advanced settings, tables, team names, carryovers, categories, etc. Hence you should aim to get the config file correct before you start making other changes in the front end.

If you are loading a config file that contains seat-assignments or carryovers, do this before people have joined the session.


List of editable config keys

(updated 5 June 2024)

Config keys for session-settings and contestant data

Key name Type Description/comments
name

String

Populates the session name, which appears in the yellow band at the top of the lobby window.

When a config file is exported, this does not appear in the config file.

announcement

String

Populates the banner announcement which appears below the yellow band in the lobby, and at the top of the scores window.

When a config file is exported, this does not appear in the config file.

table_announcements

Array of objects

Announcements to be displayed on the table before each round, or via the Info button. See Table Announcements & Information Panels

club_name

String

Club name in the Advanced menu.

club_id_number

String

Club id in the Advanced menu.

ebu_charge_code

Integer

EBU charge code in the Advanced menu (available only to clubs in the UK).

Possible values are: 0, 2, 3, 4, 6, 7, 8, 10, 11, 12, 14, 20, 21, 22, 30, 40, 50, 60, 70, 71, 90, 91, 92, 99. For a definition of these codes, see the EBU's Masterpoint and Licensing Handbook, or the dropdown list in the RealBridge Advanced menu.

When a config file is exported, this is included only for clubs in the UK

ebu_masterpoint_scale

Integer

EBU masterpoint scale in the Advanced menu (available only to clubs in the UK). Possible values:
0 = No masterpoints
1 = Club scale

When a config file is exported, this is included only for clubs in the UK

num_tables
Integer Number of tables.
In a multisession event, this must be the same for every session.
You should always include num_tables in the config file.
boards_per_round
Integer Boards per round. Usually this will be the same in every session, but it can change if required.
num_rounds
Integer The number of rounds that will be played in this session (not the total rounds in the event).
first_board
Integer The board number to start from. Defaults to 1 for every session.
Avoid having board numbers that go above 99.
scoring_method
Integer Defines the scoring method of the session, for value list, see below.
scoring_break
Boolean In round-robin matches, whether there is a break at half-time. This is equivalent to selecting the "Round-robin 2X½" movement.
auto_compass_switch
Integer

For teams events where the match is played in two halves, whether one team switches seats at half-time.
1 = Switch
0 = Don't switch

random_start_seats
Boolean

In Mitchell and Howell sessions, randomize the starting positions at the beginning of the session. When a config file is exported, this does not appear in the config file. This is because in the next session you would normally wish to continue the movement from the end of session one.

In teams sessions, randomize the NS/EW orietntation at the beginning of each match

swiss_odd_teams
String

For Swiss teams events, how to manage an odd number of teams. Either "bye" or "triple".

match_assignments
Array of integer arrays In a round-robin, Swiss teams, or Swiss pairs, the assignments for upcoming rounds.
previous_match_assignments
Array of integer arrays In a round-robin, Swiss teams or Swiss pairs, the assignments for rounds that have already been played.
team_names
Array of strings In a teams event, the names of the teams, in order (so the first name is team 1, the second name is team 2, etc.
time_per_round
Integer Time per round in seconds.
time_display
Integer How to show the remaining time.
0 = minutes only.
1 = MM:SS.
vp_scale
Integer

VP scale for session-formats that allow VPs (Round robin, Swiss Teams, Swiss Pairs and Howell).
0 = none.
1 = 20-0 discrete.
2 = 20.00-0.00 continuous.
3 = ABF.

self_alert
Boolean If set to true, use self-alerts and written explanations.
use_screens
Boolean If set to true, use screens mode.
prevent_unreserved_login
Boolean If set to true, prevents logins by usernames without a seat.
seat_assignments
Array of objects

See examples 4 and 5 above.

trick_one_delays
Array of 3 doubles Imposing delays for 1: opening lead, 2: dummy, and 3: third hand. The maximum value is 30 seconds. 
auction_delays
Array of 3 doubles Imposing delays for 1: dealers bid, 2: following three bids in the first round, 3: all subsequent bids. The default is [2,0,0]. The minimum for the dealer is 2 seconds.
allow_watching
String

Whether and when watching is allowed at the table.
"none" = Never allowed
"break" = Allowed before the session start, at the end of a round, and at the end of the session
"all" = Always allowed

impose_actions
Boolean Whether to impose bidding/play from the PBN file.
show_commentary
Boolean Whether to display text commentary on the board scorecard (traveller)
stop_each_deal
Boolean Whether to pause play at the end of each deal.
minibridge
Boolean If set to true, the session will be Minibridge rather than standard bridge
mb_flags
Unsigned number Controls the settings for Minibridge. For further information, please contact support@realbridge.online
captains
String Array of captains' names
captains_start_round
Integer Whether captains are allowed to start each round.
0 = Not allowed
1 = Allowed
vugraph
Boolean Sets up the session for a VuGraph. Automatically converts seats without seat_assignments to generic seat names, for example, 1N, 3E, etc.
big_team_size
Integer For teams-of-8 or more, the number of players in a team. Must be a multiple of 4. See Notes about scoring & movements
big_team_spacing
Integer For teams-of-8 or more, the separation between subteams in a big team. See Notes about scoring & movements
big_team_scoring
String

One of "ximps", "imps", "agg". See Notes about scoring & movements

Scoring methods

The scoring_method key specifies both the movement and the scoring method. The list of values is:

0 Practice tables (or RealBridge Lounge)
1 Head-to-head IMP teams
2 Matchpoint Mitchell
3 IMP pair Mitchell
4 Matchpoint switched Mitchell
5 IMP pair switched Mitchell
6 Matchpoint Howell
7 IMP pair Howell
14 Head-to-head BAM
17 Round-robin IMP teams
30 Round-robin BAM
33 Swiss IMP teams
34 Matchpoint Swiss pairs
35 IMP Swiss pairs
46 Swiss BAM

Config keys for categories

These keys are used to define categories and specify category values for each contestant. See Example 9 above.

Key name Type Description/comments
categories
Array of objects

One element per category. Each contains one or two nodes:

  • name: String containing the name of the category. Required.
  • sort_order: Array of strings, specifying the sort-order for this category. Optional.
category_data
Array of string arrays Category values for each contestant. The outer array contains one element per contestant. The inner array contains one element for each defined category.

Config keys for carryover scores

These keys are used in multi-session events. They are populated by RealBridge by exporting at the end of the previous session. It will not usually be necessary to create these keys manually or to edit them.

The descriptions below are a simplified explanation of how these work. If you wish to populate or edit these manually, please consult the RealBridge Support team. We are very happy to advise you, or to review config files after you have created them.

<td">

Key name Type Description/comments
co_pair
Array of doubles Total matchpoints or cross-IMPs scored by each pair or lineup.
co_pair_den
Array of integers Divisor for co_pair. The total number of comparisons contributing to co_pair.
co_pair_num_boards
Array of integers Number of boards played by each pair or lineup.
co_total
Array of doubles In teams, Swiss pairs, or standard pairs with VPs: the total score of each contestant.
co_lineups
Array of objects The pairs that have played for each team. See example 1a above.
previous_session_number_times_played
Integer The maximum number of times that any board has been played by any pair. Used in Neuberg and other factoring.

Config key for convention cards

This key is mainly used in multi-session events. It is populated by RealBridge by exporting at the end of the previous session. It will not usually be necessary to create this key manually or to edit it (though in an event with preassigned seating, you can use this mechanism to pre-populate the convention-card links).

Key name Type Description/comments
cc_links
Array of strings

Convention-card link for each pair or lineup.
In a pairs session, these are in order of pair number, as specified in seat_assignments.
In a teams session, these are in order of lineup number, as specified in co_lineups.

Non-editable config keys

Config files that you export from RealBridge may contain other keys. Do not edit or remove these unless advised to do so by the RealBridge support team.