Buzzpoint Migrator

This tool ingests JSON packet files and QBJ game files into a SQLite database. The buzzpoints app uses this SQLite database to build a web app that visualizes the data in a convenient form.

JSON packet files can be generated via these packet parsers:

• QBReader Packet Parser
• Yet Another Packet Parser (YAPP)

QBJ files are generated by MODAQ.

Usage

Preparation

1. Clone this repository via SSH, HTTPS, or downloading as a zip.
2. Install Node.js and npm on your system if they're not already installed.
   • Node.js version 22.12.0 is the recommended version. better-sqlite3 has some issues with Node.js version 24.* that you might run into.
3. Open a bash shell (e.g. Terminal), go to the root directory, and run npm install.
   • This command will install all the necessary libraries.

File Structure

Tip

The following directions go over creating the file structure from scratch. To jump ahead of many of these steps, unzip the data.zip file in the root of this repository.
This will create a data/ folder with demo /question_sets/ and /tournaments/ subfolders that you can modify to fit your needs.
Once you modify the demo and add your question set JSONs and tournament QBJs, you can skip to building the database.

1. Create a directory called data in the root directory of the project.

2. Inside data, create folders called question_sets and tournaments.

3. In question_sets, add folders for each of the question sets you'd like to add to the database.

   • In each question set folder, add an index.json file in the following style:

     {
         "name": "2023 Chicago Open",
         "difficulty": "Open",
         "metadataStyle": 1,
         "format": "powers",
         "bonuses": true
     }

   • Acceptable values for metadataStyle are listed below. 1 is default (and probably what you need).

     • metadataStyle is required if you'd like the questions table to populate with category and author data.
     • You can modify the code in metadata-utils.js if you need a custom format.

   • Acceptable values for format are listed below. powers is default.

   • If the set doesn't have bonuses, set bonuses to false.

   • If the set's metadata lists authors second instead of first (i.e., in the order <Category, Author> or <Category, XY>), set authorFirst to false.

4. In each subfolder of question sets, add a folder called editions. Each subfolder in editions corresponds to a version of the question set. Each editions subfolder should have an index.json file with properties name and date.

   • For instance, if 2023 Chicago Open has an edition that was played on August 05, 2023, create a subfolder in editions called 2023-08-05 ¹:

     {
         "name": "08/05/2023",
         "date": "2023-08-05"
     }

5. In each subfolder of editions, add a packet_files subfolder containing the MODAQ packet json files for that version of the question set.

   • It's recommended that your packets be named like Packet-01.json or Packet-A.json. (Ideally, something simple that can be easily parsed, using hyphens and/or underscores to separate slugs.)

6. In your data/tournaments folder, add folders for each of the tournaments that you'd like to add to the database. In each tournament folder, add an index.json file in the following format:

   {
       "name": "2023 Chicago Open",
       "set": "2023 Chicago Open",
       "edition": "08/05/2023",
       "location": "Northwestern University",
       "level": "Open",
       "start_date": "2023-08-05",
       "end_date": "2023-08-05",
       "rounds_to_exclude_from_individual_stats": [
           16,
           17
       ]
   }

   • The edition field should match the name field of the index.json of the corresponding question set edition.

7. In each tournament folder, add a folder called game_files and insert the tournament's QBJ files there.

   • Each QBJ filename should start with the string Round_, then the round number, then an underscore, e.g. Round_1_Team_One_Team_Two.qbj.
   • The QBJs don't have to be stored all together; you can store them in separate subfolders under the game_files folder (e.g., by round, where QBJs for round 1 are stored in game_files/round_1/).

8. Your data subfolder should now be structured like this:

   .
   |-- question_sets
   |   |-- 2023_Chicago_Open
   |   |   |-- editions
   |   |       |-- 2023-08-05
   |   |           |-- packet_files
   |   |               `-- Packet_1.json
   |   |               `-- Packet_2.json
   |   |               `-- ...
   |   |           `-- index.json
   |   |   `-- index.json
   |-- tournaments
   |   |-- 2023_Chicago_Open
   |   |   `-- game_files
   |   |       `-- Round_1_X_Team_One_Team_Two.qbj
   |   |       `-- Round_2_X_Team_Three_Team_Four.qbj
   |   |       `-- ...
   |   |   `-- index.json
   

Building the Database

• Return to the bash shell and run npm run initDB.
  • This command will build the database and store it as database.db.
• Copy database.db to the data folder of your local deployment of the buzzpoints app.
• Follow the directions in that repository to host the buzzpoints app locally and/or online.

Metadata Styles

Format	Number	Examples
"default"	1	<XY, Category> or <XY, Category - Subcategory> or <AuthorName, Category> or <AuthorName, Category - Subcategory>
"noAuthor"	2	<Category>
"authorAndCategory"	3	<XY, Category> or <XY - Category> or <AuthorName, Category> or <AuthorName - Category>
"nsc"	4	<AuthorName, Category - Subcategory - Subsubcategory> ... <Editor: EditorName>
"nasat"	5	<AuthorName , Category>
"qbReader"	6	<Category - Subcategory - Subsubcategory>
"none"	7	None

Question Set Formats

Format	Number	Powers	Superpowers	Negs
"acf"	1	❌	❌	✅ (-5)
"powers"	2	✅ (15)	❌	✅ (-5)
"superpowers"	3	✅ (15)	✅ (20)	✅ (-5)
"pace"	4	✅ (20)	❌	❌

Credits

This tool was created by Jordan Brownstein. Ani Perumalla contributed some features after its initial development.

Thanks to Anderson Wang and Geoffrey Wu for their feedback on the tool, and to Geoffrey for letting us steal subcat-to-cat.json from his packet parser.

Footnotes

1. The name field doesn't have to correspond to a certain date, you can call it whatever you want as long as the edition of any corresponding tournament matches it. ↩