NX Multiplayer Communications Standard

• Discussion

SP4CEBAR 2026-08-16 15:53 (Edited)

order in multiplayer

I noticed that the icloud-based multiplayer programs are taking off, great!

However the current version of my multiplayer demo game doesn't handle disks very well that were used by other programs or that were shut down incorrectly.

So I would like to propose this standard to allow programs to understand each other, and detect ended games so they know when it is safe to reset a Disk. I haven't implemented it yet in the demo.

I would like to know what you think about it and if it fits your use cases

simplest version of the standard

To get started, here is the simplest version of the standard.

1. implement file 0's name (see below)
2. implement the first two bytes of file 0 (see below)
   • the second byte should hold the number 3 to tell that you used the simple version

the full standard

File 0's name

File 0's name should hold the program name and version to allow other programs to check compatibility,

• the name has to be prefixed with "online" to tell that this is a compatible disk
• version is a suffix in format "v0.1" where any number may have multiple digits

File 0

File 0 should hold:

• the game's player count (1 byte number),
  • player count of 0 means that the disk is safe to be reset by other programs
• the file layout (1 byte, see options below)
  • 0: my demo game: settings in file 2, variable settings in file 1 (this is what my demo used)
  • 1: settings at the end of file 0, variable settings in file 1
  • 2: compact version: settings and variable settings at the end of file 0 (variable settings first)
  • 3: simple version: only the file 0 naming convention, player count, and this byte are used, the rest of the standard isn't
  • 4: files 1 to 3 are reserved for settings, variable settings in file 1
  • 5: files 1 to 4 are reserved for settings, variable settings in file 1
  • 6: files 1 to 5 are reserved for settings, variable settings in file 1
  • 7: files 1 to 6 are reserved for settings, variable settings in file 1
  • 8: files 1 to 7 are reserved for settings, variable settings in file 1
  • 9: files 1 to 8 are reserved for settings, variable settings in file 1
  • 10: files 1 to 9 are reserved for settings, variable settings in file 1
  • 11: files 1 to 10 are reserved for settings, variable settings in file 1
  • 12: files 1 to 11 are reserved for settings, variable settings in file 1
  • 13: files 1 to 12 are reserved for settings, variable settings in file 1
  • 14: files 1 to 13 are reserved for settings, variable settings in file 1
  • 15: files 1 to 14 are reserved for settings, variable settings in file 1
  • 16: files 1 to 15 are reserved for settings, variable settings in file 1
• connection testing, (1 byte, see options below) (see recommendations for the testing procedure)
  • 0: no test active
  • 1: external party wants anyone to respond in the fixed order
    • using the second byte of the variable settings to say who should respond
  • 2: external party wants anyone to respond
• game type (1 byte, see options below)
  • 0: turn-based (like most card games)
  • 1: reveal (like rock paper scissors)
  • 2: sync (game states are synched like terraria)
  • 3: chat (data is meant to stay)
• timeout duration (1 byte, number in minutes)
  • 0: no timeout, use when a turn may last days
    • player ID can be stored in persistent RAM and player's can re-join
• spectator count (1 byte number)
• and settings (the rest of the file, store any data you like)

File 1

File 1. Stores variables that change regularly, this is moved to file 0 if set by the second byte of file 0

• turn ID (1 byte number) the ID of the player at play
• player ID that should respond automatically (1 byte number) (to allow ordered tests from the third byte of file 0 to be executed)

settings files

Depending on the second byte of file 0, there may be one or more settings files.

Remaining Files

All remaining files are assigned to players:

• the first byte holds their move,
• the next two bytes holds the player's timer value at the time of their last modification
• the rest is for additional information about their move or whatever this player should transmit

name of remaining files

The file name is the player's nickname

Recommendations

Checking Compatibility

• if the disk's name and version do not match the current program's compatible versions list then it should not proceed until the disk is reset
• the disk may only be reset if the name is prefixed "online" and the player count is 0 (the first byte of file 0)
  • if the player count isn't 0 and the type isn't chat (see file 0) and the timeout duration isn't 0 (see file 0) then we can determine if the game ended, and is safe to reset, using one of these methods below.
    1. no player client responded to a connection test (see connection testing below)
    2. the person at play times out (you need to be able to sync timer values with the next session somehow)
    3. or the user trying to play a new game confirms a prompt to reset the disk

Settings conventions (as I don't know how reliable icloud is here)

• use settings for constant variables
• the settings are specific to the program and do not have to be understood by all compatible programs
• it is recommended if only the "host" (first player) should be allowed to change file 0 (as I don't know how reliable icloud drive is here)

player timeout

NX doesn't have a built-in way to detect if a program stopped, so a multiplayer program should provide its own exit button

each player's timer value should be sent whenever they change their file so that any client can determine if a player timed out

In case a player did not exit correctly, each client should store the timer values it received from each player as well as the time it was sent on and the offset with its timer to check the other player's response time, if the player at play takes longer than the timeout duration stored in file 0 then they get kicked as they may have quit.

a second player could replace the host if the host quit and so on until there's only one player and the game stops and is reset

connection testing

the third byte of file 0 is used for connection testing, it should be left at 0, only an external party may set it to see if anyone is still connected, any connected player responds by sending their current timer value in their own chsnnel. If this causes version conflicts in icloud drive, then the value could be set so that only the players have to respond in a specific order so that the external party can check each of them. The second byte of the variable settings section is reserved for a connection testing round. A connected player such as the host may, if no test is active, set the second byte of the variable settings to ask someone's client if they are still connected

Without connection testing here are some alternative ideas to determine an ended session. Maybe even a new session could determine if the previous session is times out and know if it's safe to reset it, but to do that it may need to prompt the host for the date and time. Alternatively the new session could wait 5 minutes to see if the game from the disk is still active or prompt its user if the disk may be reset.

spectators

• I added a spectator count to file 0 to give give spectators IDs which could make it possible to replace players that left with spectators
  • I define a spectator as a player who (generally) does not write anything to the disk (the spectator count byte would be the exception)

long duration games

• you can store the player's own ID in persistent RAM so that each player can re-join later. You can set the timeout byte to 0 to remove the timeout.

forwards compatibility

This format may change, so be sure to make your program not freak out if it reads a type number that is greater than 16

Ideas

Sync timers

• users could send the difference between their timer value and the host's timer value to allow others to determine the connection speed of each user
  • this would make it a lot more complicated
• a manually entered date could be stored to allow a future player to detect a timed out session

branch

If you have some great ideas that benefit general communication between programs for this format, you could add your own type to the second byte of file 0 that would hold your special file format, note that older multiplayer programs wouldn't be able to read it

• just make sure to tell others by sending it here and have no one else use the same type number as you

SP4CEBAR 2026-08-16 16:07

I haven't implemented any of it yet so feel free to suggest changes to ensure it fits your use cases

SP4CEBAR 2026-08-16 16:38 (Edited)

Edit 1:

• program name and version would now be stored in file 0's name instead of file 0's file data
• file name should be prefixed with "online" to tell that it is compatible with this standard

SP4CEBAR 2026-08-16 16:58 (Edited)

The format is not (edit: it is now) backwards compatible with my multiplayer demo as I find efficiency to be more important.

Let me know if your project was built on the demo and you would like backwards compatibility

SP4CEBAR 2026-08-16 18:14

Update 2

• backwards compatibility with my multiplayer demo
• the second byte of file 0 configures the location of settings
• settings may be moved to file 3 if the byte mentioned above is 0, this lines up with the demo mentioned above

SP4CEBAR 2026-08-16 18:50 (Edited)

Update 3

• option 2 for the second byte of file 0 changed

SP4CEBAR 2026-08-17 09:01

Update 4

• added a fourth file layout option to use the minimal functionality of this standard, use this when your use case doesn't fit the standard very well

SP4CEBAR 2026-08-17 09:14 (Edited)

Update 5

• added 12 more file layout options to reserve disk files for settings

SP4CEBAR 2026-08-17 09:15 (Edited)

In a week from now you may assume this format to be locked, as in, I won't change it drastically and it would remain backwards compatible

SP4CEBAR 2026-08-17 09:45 (Edited)

Update 6

• added communication tests to find if anyone is still connected to a session

SP4CEBAR 2026-08-17 14:58 (Edited)

Update 7

• add game type and timeout duration to file 0

moechofe 2026-08-17 15:58

Putting data into File#0 will disable the internal font.

Timo 2026-08-17 22:15

Moechofe, that does not apply for the data disk, only for the runnable program itself.

moechofe 2026-08-18 05:26

I was thinking, if two players modify the same Disk at the same time who will win?

moechofe 2026-08-18 05:28

Second question: Disk exist because the FILES command requires a target. So it's possible to share other programs than Disk and open the game like it was an editor, will it works?

moechofe 2026-08-18 07:25

I mean, if it works, it does not requires user to rename/remove/re-add Disk.nx every time they want to do something else.

Timo 2026-08-18 08:35

File conflicts would be handled by iCloud Drive. Actually I’m not sure what would happen exactly.

SP4CEBAR 2026-08-18 16:08 (Edited)

@moechofe, that's a great idea actually! You can already do this:

1. Add your favorite multiplayer program as a tool
2. open a shared NX file (it would be beneficial if the shared files had names other than Disk.nx so that it can coexist with your local Disk.nx file)
3. Launch the multiplayer program as a tool

I likely won't be adding more shared disks any time soon. But you can easily create a new icloud account on icloud.com which would get you 1GB (instead of the usual 5GB) of drive storage, this is plenty to share disks, then give everyone read and write access to these files and you can use them, see how to share a disk for more details

SP4CEBAR 2026-08-18 16:21

Neither do I know how icloud drive handles version conflicts, my testing included local tests with multiple NX instances, as well as tests where I manually changed the shared Disk on icloud while a multiplayer program was running, but no version control tests