Intro

NEStrisChamp works with the concepts of room. Each user has 2 rooms:

• A single-player Private room - to capture your own gameplay.
• A multi-player Match room - to organise and comment on other player matches.

The key is for players to OCR their game frames into the correct room.

For single player rooms, you just need to send your game frames into the room and into the view for them to be rendered.

For Math room, you may invite as many people as you want to be producers, and you'll select who, out of the room members, gets to be player 1 and player 2.

Architecture and Terminology

In single player mode, frame data is passed straight from the producer into 1 or more views.

In competition mode, all producers emit data, but the room owner assigns a given producer to be player 1 and another producer to be player 2. Only the game frame of these 2 players are sent to the views.

• Room: A broker of connection, frame data, and commands
• Producer: an entity doing 1) OCR and 2) emitting frames into the room
• View: Receives the frame data and redraws the scene, can accept other commands (e.g. to set player names)
• Admin UI: For Multi player rooms, the admin room allow the room owner to control which producer are player 1 and player 2, Update the player names, and assign victories.

URL scheme

Views

Since views are typically setup in OBS, the URL needs to identify the room owner by itself, This is achieved by assigning a secret to each user that can placed in the URL. It's not super secure, but whatever, this tool is not hosting state secrets -_-

http://nestrischamps.io/view/LAYOUT_NAME/USER_SECRET

The layouts available so far are as follow:

• Single Player
  • classic: a stats-heay interface for classic rom
  • das_trainer: a stats-heay interface for the DAS trainer rom
  • simple_1p: a simple UI with Tetris rates and Droughts
  • invisible_tetris: A renderer for Invisible Tetris
  • qualifier: Minimalistics stats to add to your Stencil
• Multi Player
  • ctwc: A CTWC inspired layout
  • ctjc: a CTJC inspired layout
  • ctjc_pace: a CTJC inspired layout with pace metric
  • ctm: a CTM inspired layout

At your first login, a secret would have been generated for you and added to your user record. You can see it in your personal renderer links which are available here.

Hopefully in the future, users will be able to contribute their own template.

Several of the layouts have a black background with Tetris pieces. If you do not like it and would prefer a transparent background to place the layout above it, add the query string `?bg=0` into the view URL. Like so:
http://nestrischamps.io/view/LAYOUT_NAME/SECRET?bg=0

Producer

To produce frames into your own private room, visit https://nestrischamps.io/room/producer

To attach yourself as a producer to another user's room (typically the link will be passed to you as an invitation), the links will be of the form

https://nestrischamps.io/room/u/TWITCH_USERNAME/producer

Admin

To administer your competition room, visit https://nestrischamps.io/room/admin

OCR and Calibration

OCR is supported in browser for both device capture and screen capture.

2 default game roms are supported:

• Classic Tetris

  

• Das Trainer

  

The fields that need to be OCR-ed per rom are fixed (see highlighted areas above)

There is a built-in automatic calibrator but it doesn't work to well, so you should always ajust the areas selected for calibration to be as close as possible to the desired outcome.

In both cases, start a game at level 0 BEFORE you press the "Calibrate and Capture button". In Das trainer, pause as soon as the game starts click the button. In Classic Tetris, click as soon as the game starts. In both cases, keep your fingers crossed that the auto calibrator takes you close to the desired state, and then fine tune all the capture areas to be pixel perfect.

Once calibration and tuning has been done, the capture window and the browser tab MUST stay focused.

Digits

The capture area should "hug" the digits on top, right, bottom, left, (using 0 as a reference), like this:

Note that if you calibrate something that starts with a 1, the capture area should NOT hug the one on the left (notice the black strip on the left).

Preview

To calibrate the preview properly, run the calibration in level 0 over multiple pieces, such that:

• Pieces S, Z, L, J, T, O are "hugged" TOP and BOTTOM in the capture area

  

• Piece I is "hugged" LEFT and RIGHT in the capture area

  

"hugged" means there is no black border

Current Piece (DAS Trainer only)

To calibrate the preview properly, run the calibration in level 0 over multiple pieces, such that:

• Pieces L, J are "hugged" TOP ONLY in the capture area (notice there's a black strip at the bottom)

  

• Pieces S, Z, T, O are "hugged" BOTTOM ONLY in the capture area (notice there's a black strip on top)

  

• Piece I is "hugged" LEFT and RIGHT in the capture area

  

Colors (Classic Tetris only)

Reading colors from the frame helps matching the block colors when scanning the field.

The are 3 colors to read: color1, color2, and color3. They should be read from the pieces stats on the left by selecting one block from the T piece, J piece, and Z piece.

The blocks should be chosen like this

The selection should not include any black border, but color1 should include the block's border. They should look like this

Field

To calibrate the field capture, try to stack pieces on the left, right, and bottom, and even all the way up on the top-left and top-right.

Having done that, hug the capture on right, left, top, bottom. do not leave black borders at the bottom and right!, like this:

OBS / Streamlabs setup

All layouts so far are 720p (1280x720), which is a good compromise of real estate vs. draw time and upload bandwidth requirements. But feel free to stretch the layout to fit a 1080p canva

The Browser Source setup should look like this:

Administering a Room

In the admin panel, you get to see who is connected to the room, and select the desired producers as player 1 and player 2

The Name and Avatar are taken from Twitch data, but can be updated to suit.

The number of match to get to victory can change ("Best of" dropdown)

Each player has a heart control, the heart can be clicked to attribute victories.

The "Winner" button displays a little animation in the field to show the winner and loser of the match. Do NOT click it until both players have topped out! If the winning player is chasing a maxout or what not, wait till he/she is done before clicking.

Finally the "Clear Victories" button resets the victory for both players to 0, and stops the winner animation.

Binary frame format

All captured frames are sent in binary and weight 568 bits (71 bytes) per frame. On a capture setup of 60fps, the game stream requirements are therefore 71*60 = 4,260 B/s (~4KB/s).

They have the format below.

Game fields may be null (like das trainer's instant das when sending classic frames), in which case the field's bits should all be set to 1.

Below is the bit representation of the fields described above

See the source file for implementation details.

Ideas for improvements

As with any software, there's always more... "More, more, more, more, more" as the GOAT would have said.

The list of TODO items is tracked as issues in the github project. Feel free to open feature requests and bug reports there. There's no ETA and guarantee on when anything might get done though, so patience is key :).