Reference for Scripted Tree Building

Scripted tree building in HRC is a powerful feature that enables users to create fully customized decision trees using simple scripts. This functionality streamlines the process of setting up calculations and reduces the need for manual pruning. Users can define spot-specific rules, such as opening sizes and calling options depending on position, separate sizings for squeeze spots, and custom postflop sizings based on stack-pot-ratio. Get started with provided example scripts and learn to customize them to suit your needs, or write your own scripts to create the perfect tree configurations for your poker analysis.

Scripted Tree Building

With the introduction of the postflop model, users started to really push the UI based tree setup in HRC to its limits. Scripted tree building allows full customization of the tree building process with the help of simple scripts. This feature is only available for Monte Carlo hands and only for users with a HRC Pro license.

Scripting can remove the need for excessive manual pruning after the tree creation. It also enables users to define their desired betting setup once and then re-use the script for any number of calculations.

Screenshot of Script Settings

The core idea is that users still configure the stacks, blinds and equity model via the user interface. However, instead of entering globally allowed raise sizes and flat calling options in the user interface, users can provide a script with spot-specific rules. The script has access to the full game state for each decision point, including all previous actions.

With access to the game state it's straightforward to implement rules that go beyond our UI capabilities, for example:

  • Define bet and raise sizes and calling options depending on the player's position
  • Configure various sizings postflop, depending on the effective stack-pot-ratio
  • etc.

Getting Started: Default Example

Let's get the very first scripted build out of the way:

  • Start a new Advanced Monte Carlo hand.
  • Setup stacks and select an equity model as usual.
  • Download the default example script (Use right click: Save link as...)
  • Click Next to go to the bet sizing setup and select the Scripting tab.
  • Use the Open Script button and select the downloaded file.
  • HRC will automatically start to estimate the size of the resulting tree, updating the figures in the bottom table.
  • Wait until the estimate is done, then click Finish to actually create the tree.

Nice, you have created your first scripted tree!

The default example script closely resembles the options from the UI when using the advanced preflop setup. You can use this as a starting point for adjustments.

Customizing the default example

Don't get discouraged by the code, customizing the script is simple and doesn't require any coding skills.

You can use any text editor to customize the script. We can recommend Geany as a free and lightweight option that is available for Windows, OSX and Linux. Using Window's default text editor is also fine, but you won't have the colored syntax highlighting.

You already downloaded the example earlier, now let's open it in Geany. You should see the syntax colored similar to the "Show example source" option below. Focus on the first few lines where the sizes are defined, it's no more complicated than changing those values and saving the file. Then simply load the modified version in HRC, that's it!

Show example source

If you want to modify the behavior beyond changing the existing settings then take a look at the API and Resources section, especially our HRC Scripting GPT.

Additional examples

In this section we'll provide a selection of scripts for some common tree configurations. These scripts were created in collaboration with the HRC Discord Community, you can find additional examples pinned in the #scripting channel.

Writing your own scripts

To write your own scripts, some coding experience would be helpful. The scripts are written in JavaScript, but if you know any C-like language (C, C++, C#, Java,...) this should be sufficient. If you have any requests or problems with the scripting API then please let us know via discord in the #scripting channel. You can also post your custom scripts there if you need help.

API and Resources

  • HRC Scripting on chatGPT, this is a custom GPT instance with direct access to the HRC scripting API and example scripts. It can help you with creating, modifying or debugging scripts. Requires a chatGPT Plus subscription.
  • API Documentation, the complete API documentation
  • ITreeBuildingScript, defines the methods that need to be implemented by the script
  • IDecisionContext, documentation about retrieving the game state
  • Geany, lightweight editor with JavaScript syntax highlighting

Key Clarifications and Programming Guidelines

  • JavaScript for Scripting: Despite HRC's Java foundation, scripts must be written in JavaScript due to the incorporation of Graal's JavaScript engine.
  • Handling Arrays: When an API method returns an Array, it should be wrapped using Array.from(...) before applying any JavaScript methods to ensure proper handling.
  • Decision Context Methods: All methods called on the ctx object must align with those in the IDecisionContext API.
  • Stateless Script Execution: Avoid using global or external variables for tracking the game state or history. Rely solely on the context (ctx) for all information about the current game state.

Constants and Player Positioning

  • Constants: Use constants from ITreeBuildingScript (like FOLD, CHECK, CALL, RAISE, PREFLOP, FLOP, TURN, RIVER) directly without qualifiers for clarity and simplicity.
  • Player Position Methods: Utilize ctx provided methods for determining player positions like Small Blind (SB), Big Blind (BB), and Button (BU).
  • Relative Positioning: For positions other than BU, SB, and BB, calculate indices relative to the Button, e.g. CO would be ctx.getPlayerIndexButton() - 1.