Skip to content

Generator Bases Documentation

Warmy edited this page Sep 27, 2023 · 4 revisions

Where possible the following generators are ordered by functionality and complexity

Simple

Documentation last updated: Sep 26 2023

Features:

  • random placement
  • no duplicate goals

Structure of bingoList:

Its a list of goals of one of the two following formats.

An example can be found here: https://github.com/kbuzsaki/bingosync/blob/main/bingosync-app/generators/a_bugs_life_generator.js

/**
@type {
  name: string,
}[]
*/
[
  // all goals listed
  {
    // text shown on the bingo card
    "name": ""
  },
  ...
]

An example can be found here: https://github.com/kbuzsaki/bingosync/blob/main/bingosync-app/generators/bloodborne_generator.js

/**
@type string[]
*/
[
  // all goals listed

  // text shown on the bingo card
  "",
  ...
]

Generation method:

The board will be 5x5. In order from left to right and top to bottom, for each square, a random goal is chosen from the list. Goals will be picked only once per board.

Notes:

  • The first way to structure the the json is similar to other generators, so it might be preferable if one wants to switch to a more advanced generator later on.

Simple (ALttP)

Documentation last updated: Aug 9 2021

The Simple generator, but only one goal starting with Finish is allowed on the board.

LADX

Documentation last updated: Sep 26 2023

Features:

  • random placement
  • no duplicate goals
  • categorizing of goals to have only one per category on the board

Structure of bingoList:

An example can be found here: https://github.com/kbuzsaki/bingosync/blob/main/bingosync-app/generators/links_awakening_switch_generator.js

/**
@type {
  name: string,
  group: string,
}[]
*/
[
  // all goals listed
  {
    // text shown on the bingo card
    "name": "",
    // group common for several goal
    "group": "" // can be omitted
  },
  ...
]

Generation method:

The board will be 5x5. In order from left to right and top to bottom, for each square, a random goal is chosen from the list. But goals that have the same group value as any goal that has already been placed on the board are excluded. There can only be one goal with a certain group value on the entire board. Goals can only appear once on the board.

Notes:

  • //

Isaac

Documentation last updated: Sep 26 2023

Features:

  • random placement in the difficulty groups
  • no duplicate goals per difficulty group
  • categorizing of goals to have only one per category on the board
  • weighting of goal difficulty with a fixed difficulty layout

Structure of bingoList:

An example can be found here: https://github.com/kbuzsaki/bingosync/blob/main/bingosync-app/generators/binding_of_isaac_generator.js

/**
@type {
  name: string,
  types: string[],
}[][]
*/
[
  // a list of four arrays representing easy, medium, hard and extrem hard difficutlies in that order
  [
    // goals listed
    {
      // test shown on the bingo card
      "name": "",
      // type categories
      "types": [] // defaults to empty list
    },
    ...
  ],
  ...
]

Generation method:

The board will be 5x5. Each square will be assigned a fixed difficulty by the following pattern:

medium hard easy easy medium
hard easy medium medium easy
easy medium extrem hard medium easy
medium easy medium easy hard
easy medium easy hard medium

In order from left to right and top to bottom, for each square, a random goal is chosen from the goal pool of its difficulty. But goals that share a type with any goal that has already been placed on the board are excluded. Goals can only appear once on the board.

Notes:

  • Several difficulty groups can draw from the same pool if setup in a certain way. Add the name of the goals as a type, for each goal in the pool. Duplicate the array for all difficulties that should share it. This ensures that a goal cannot be placed on the board twice, as the type rules disallow it board wide.
  • The types should not be overused, but only to create board wide exclusive groups.

SRL v5

Documentation last updated: Sep 26 2023

Features:

  • random placement of all 25 goal buckets each on exactly one of the 25 squares of the board
  • random picking of one goal per bucket starting with the top left square
  • no duplicate goals only per goal bucket
  • categorizing of goals to prefer no goals with the same category within any bingo line (works poorly if not used correctly, read the entire section for details)
  • weighted categories where the first category listed is counted twice and all following are counted once

Structure of bingoList:

An example can be found here: https://github.com/kbuzsaki/bingosync/blob/main/bingosync-app/generators/super_mario_odyssey_generator.js

/**
@type {
  name: string,
  types: string[],
}[][]
*/
[
  {}, // zero-index is ignored
  // exactly 25 difficulty buckets
  [
    // goals listed
    {
      // text shown on the bingo card
      "name": "",
      // type categories
      "types": [], // defaults to empty list
    },
  ],
]

Generation method:

The 25 difficulty buckets are randomly placed onto the squares of the board. Each bucket gets assigned exactly one square. In order from left to right and top to bottom, for each square, a random goal is chosen from the bucket of the difficulty that was assigned to that square. But goals that share a type with any goal that has already been placed on a bingo line of the current square are at disadvantage. Specifically the synergy is calculated for all bingo lines by counting each type that appears in the currently checked goal as well as in any other goal on a bingo line. Additionally if the type that appears in two goal is the first in the type list it is counted twice and not only once. If the synergy is zero (there are no other goals yet that share a type with the goal), the goal is immediately picked and the next square gets calculated. If not, the goal with the least matching types (the least synergy) is chosen. If two goals have the same synergy value (e.g. one has 1 first type listed overlap and the other has a second and third type listed overlap) the first one that is encountered is chosen. Which, because of implementation detail results in a random goal from those with the same synergy value. If all goals have the same synergy value, the last one encountered is chosen. Which, because of implementation detail results in a random goal from the bucket.

Notes:

  • To prevent the first type be counted twice one could add a placeholder type the beginning of the types of every single goal. Either enumerated or all with a same value that will definitely not be used as a real type.
  • As the buckets are placed first and chosen sequentially, if at first a goal with a certain type is picked and the next bucket in its bingo line only contains goals that share that type, the synergy avoiding will not work. This can be avoided by better planning the buckets and types.
  • If goals in separate buckets have the same name, the generator might place them on the same board or bingo lines, as it is not using the name at all. One could use the name as a type but that will only prevent the two goals to be on the same bingo line not the board in general and for certain setups not even that will work.
  • There is no use in having a type that is same for the entire difficulty group, as then all or none will trigger a synergy, and just defuse the results.
  • The SRL v8 code is way better documented and quite similar, if one tries to understand the code they should look into the v8 first.

SRL v5 (Blackout)

Documentation last updated: Aug 9 2021

SRL v5, but instead of checking bingo lines for synergies, it checks the whole board (for blackout bingo).

SRL v8

Documentation last updated: Sep 26 2023

Features:

  • random placement of the 25 goal buckets onto the 25 squares of the board. (There can zero one, or multiple goals from a bucket on the board, if the categories could not be followed otherwise)
  • random picking of one goal per bucket starting with the most difficult buckets, center, diagonal and then the rest
  • categorizing of goals to prefer no goals with the same category within any bingo line
  • weighted categories where the first category listed is counted twice and all following once

Structure of bingoList:

Uses name/types system from SRL v5, but adds child tag (require child for MODE="short", otherwise prevent all-child bingos)

An example can be found here: https://github.com/kbuzsaki/bingosync/blob/main/bingosync-app/generators/terraria_1_3_generator.js

/**
@type {
  name: string,
  types: string[],
  child: string, // "yes"|"no"
}[][]
*/
[
  // exactly 25 difficulty buckets
  [
    // goals listed
    {
      // text shown on the bingo card
      "name": "",
      // type categories
      "types": [], // optional, defaults to empty list
      // child field
      "child": "no" // optional, defaults to no
    },
  ],
]

Generation method:

The generation is very similar to v5 therefore only the differences are listed. When choosing the goal from a bucket it no longer follows the simple pattern from v5 but generates a partially random order. The three most difficult squares will be picked first, then the center square, then the diagonals and then the rest. The diagonals and the rest will be shuffled in themself. In the process of choosing a goal from a bucket it is no longer limited to choose only from the pre picked bucket. Instead, if there is no type with a synergy value of 0 (so no overlapping types at all), the next bucket (in the order they were listed in the JSON) will be searched through. Only if there is not a single goal with a synergy value of 0, in the pre picked or any more difficult buckets, the goal with the minimum synergy over all the buckets looked into is chosen. There is a new child functionality that is currently UNDOCUMENTED here but also not used in any public boards.

Notes:

  • Due to the option to pick from harder buckets, the difficulty should be less consistent then v5.
  • Due to the option to pick from harder buckets, the guarantee to have one square from every bucket is no longer true in compared to v5.
  • Due to the way the more difficult buckets can be searched through for goals and that it only considering bingo lines, it should theoretically be possible for a goal to appears multiple times on the board.
  • To prevent the first type to be counted twice in the synergy calculation one could add a placeholder type the beginning of the types of every single goal. Each must be unique so its easiest to enumerated them. (using the same value for all the placeholders will break the generation for v8 as the synergy value would never be 0 and therefore the pre picked bucket would no longer have any meaning)

SRL v8 (Subtypes)

Documentation last updated: Sep 26 2023

SLR v8 but with UNDOCUMENTED additions.

SynerGen

Documentation last updated: Aug 9 2021

Features:

  • Undocumented

Structure of bingoList:

An example can be found here: https://github.com/kbuzsaki/bingosync/blob/main/bingosync-app/generators/hollow_knight_item_rando_cursed_generator.js

/**
@type {
  bingoTypes: {
    [typeKey: string]: { Max: number },
  },
  maxScore: number,

  [goalKey: string]: {
    Desc: string,
    Diff: number,
    Types: typeKey[],
    Excludes: goalKey[],
    Synergy: (goalKey | (synergyKey: string))[],
    Score: number,
  }
}
*/
{
  // required initialization
  "bingoTypes": {
    "TypeName": {
      "Max": 5, // defaults to 5
    },
  },
  "maxScore": 0,

  // goals
  "goalKey": {
    // Text shown on the bingo card
    "Desc": "#!#key#!#", // defaults to `#!#{goalKey}#!#`
    // Difficulty bucket of the goal 1-25; a value of 0 is a wildcard that fills whatever difficulty
    "Diff": 0, // defaults to 0
    // Goal categories; a maximum number of goals with the same category are included (max chosen in `bingoTypes`)
    "Types": [], // defaults to []
    // Other goal keys that should not appear on the same board as this goal
    "Excludes": [], // defaults to []
    // Other goal keys that should be more likely to appear on the same board as this goal
    // Alternatively, synergy keys that are not goal keys; goals sharing a key are considered synergistic
    "Synergy": [], // defaults to []
    // Separate mechanism for limiting the board: the cumulative "score" is tracked for a board,
    // and the sum of all goals' score is not allowed to exceed `maxScore`
    "Score": 0, // defaults to 0
  },
}

Generation method:

Undocumented

Notes:

  • //

OOT

Documentation last updated: Sep 26 2023

Features:

  • Undocumented

Structure of bingoList:

Undocumented

Generation method:

Undocumented

Notes:

  • //