Table of Contents

Class BlackjackEnv

Namespace
Gym.Environments.Envs.ToyText
Assembly
Gym.Environments.dll

Blackjack-v1: beat the dealer without going over 21. The player hits (1) or sticks (0); a hit that busts loses (-1.0), sticking plays the dealer's hand out (drawing below 17) and scores the game (1.0 win, -1.0 loss, 0.0 draw). natural pays 1.5 for a winning natural blackjack; sab (Sutton and Barto's rules, Blackjack-v1's registered default, which overrides natural) makes a natural against a dealer without one an automatic win. Byte for byte what Gymnasium's Blackjack computes: the cards drawn from the generator (an infinite deck, np_random.choice), the face-up card's suit and face, observations, rewards and rgb_array pixels.

public class BlackjackEnv : Env<object?[], NDArray>, IEnv, IDisposable, IDynamicAttributes
Inheritance
BlackjackEnv
Implements
Inherited Members
Extension Methods

Remarks

Observations are Gym.NET's tuple, object?[] (what the Tuple(Discrete(32), Discrete(11), Discrete(2)) observation space samples), of three new 0-d int64 arrays the caller owns: (player_sum, dealer_card, usable_ace). BlackjackObservation reads one by name (DR-13). Rewards are Gymnasium's float64 values; the info is empty. A step asserts the action against the space first (Gymnasium's bare assert), so only 0, 1, True, False and 0-d integer arrays of those values pass.

A reset draws the dealer's two cards, the player's two, the face-up card's suit and, for a ten, its face (J, Q or K): five or six draws, in Gymnasium's order. Nothing stops a step after the game ended: the hand goes on, as in Gymnasium. Rendering draws Gymnasium's pixel-art table (the digits are images, no font); human mode renders into the window from viewer_factory or Gymnasium.HumanViewerFactory (DR-20) at 4 frames per second, and any other mode returns the frame. Not thread-safe.

Reference: gymnasium/envs/toy_text/blackjack.py.

Its info is always {}, as Gymnasium's, so it has no typed info record (DR-95).

Constructors

BlackjackEnv(BlackjackEnvOptions)

Builds the instance from its options record: the properties set, the constructor's defaults for the rest.

public BlackjackEnv(BlackjackEnvOptions options)

Parameters

options BlackjackEnvOptions

The options.

Exceptions

ArgumentNullException

Thrown when options is null.

BlackjackEnv(RenderMode, bool, bool, EnvViewerFactory?)

Builds the env with the render mode given as the RenderMode enum (DR-84, DR-93), as BlackjackEnv(string?, bool, bool, EnvViewerFactory?) builds it from the mode's string: new BlackjackEnv(RenderMode.RgbArray) builds what new BlackjackEnv(renderMode: "rgb_array") builds, the member reaching the env as Gymnasium's string (Name(RenderMode)), which its RenderMode property then holds.

public BlackjackEnv(RenderMode renderMode, bool natural = false, bool sab = false, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode RenderMode

The render mode, which the env must list in its metadata["render_modes"] as for the string; it behaves exactly as its Gymnasium string does in the other constructor.

natural bool

Gymnasium's natural: a winning natural blackjack pays 1.5 (ignored when sab is set).

sab bool

Gymnasium's sab: Sutton and Barto's rules, where a natural against a dealer without one wins outright.

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode; null uses Gymnasium.HumanViewerFactory.

Remarks

The mode is required and comes first, so new BlackjackEnv() keeps meaning the other constructor, without a mode; leave the mode out there for no rendering. Every other parameter means what it means there.

Exceptions

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare (a cast integer such as (RenderMode)99).

BlackjackEnv(string?, bool, bool, EnvViewerFactory?)

Creates the env.

public BlackjackEnv(string? renderMode = null, bool natural = false, bool sab = false, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode string

Gymnasium's render_mode: null, "human" or "rgb_array" (any other mode draws like rgb_array, as in Gymnasium).

natural bool

Gymnasium's natural: a winning natural blackjack pays 1.5 (ignored when sab is set).

sab bool

Gymnasium's sab: Sutton and Barto's rules, where a natural against a dealer without one wins outright.

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode; null uses Gymnasium.HumanViewerFactory.

Properties

ClassMetadata

Gymnasium's class attribute metadata: {"render_modes": ["human", "rgb_array"], "render_fps": 4}. Every env starts with a copy as its instance metadata.

public static Metadata ClassMetadata { get; }

Property Value

Metadata

Remarks

A new dict on every read, so editing one env's metadata never reaches another (Python's is one shared dict).

Clock

Gymnasium's clock, null until the first render.

public Clock? Clock { get; }

Property Value

Clock

Dealer

Gymnasium's dealer: the dealer's cards, the first one face up; null before the first reset. The env appends to this very list; assigning one injects a hand.

public List<long>? Dealer { get; set; }

Property Value

List<long>

DealerTopCardSuit

Gymnasium's dealer_top_card_suit: C, D, H or S, drawn by the reset; only the frame shows it.

public string? DealerTopCardSuit { get; set; }

Property Value

string

DealerTopCardValueStr

Gymnasium's dealer_top_card_value_str: A, a digit, or the drawn J/Q/K of a ten; only the frame shows it.

public string? DealerTopCardValueStr { get; set; }

Property Value

string

Deck

Gymnasium's module-level deck: 1 (ace), 2 to 9, and four tens (10, jack, queen, king), drawn with replacement, so the deck is infinite.

public static IReadOnlyList<long> Deck { get; }

Property Value

IReadOnlyList<long>

Natural

Gymnasium's natural: whether a winning natural blackjack pays 1.5. Read at every stick.

public bool Natural { get; set; }

Property Value

bool

Player

Gymnasium's player: the player's cards, null before the first reset (Python has no such attribute yet). The env appends to this very list; assigning one injects a hand.

public List<long>? Player { get; set; }

Property Value

List<long>

Sab

Gymnasium's sab: whether Sutton and Barto's rules apply (a natural wins outright). Read at every stick.

public bool Sab { get; set; }

Property Value

bool

Screen

Gymnasium's screen: the frame every render draws on, null until the first one (Python has no such attribute yet).

public Surface? Screen { get; }

Property Value

Surface

Methods

Close()

Once a screen exists, shuts the human-mode window down (pygame's display.quit()); the screen is kept.

public override void Close()

Remarks

Cmp(double, double)

Gymnasium's cmp: float(a > b) - float(a < b), the game's score of two totals.

public static double Cmp(double a, double b)

Parameters

a double

The player's score.

b double

The dealer's score.

Returns

double

1.0, -1.0 or 0.0 (also for a NaN, which compares neither way).

Remarks

ConvertAction(object?)

The untyped step's action conversion: Gymnasium's assert self.action_space.contains(action) on the action as given (a Python True is contained, a 0-d bool array is not), then the base conversion.

protected override NDArray ConvertAction(object? action)

Parameters

action object

The action as given to the untyped step.

Returns

NDArray

The action as a 0-d array: the one given, or a new int64 one the step releases.

Exceptions

AssertionError

Thrown for anything Discrete(2) does not contain (the bare assertion).

DrawCard(Generator)

Gymnasium's draw_card: int(np_random.choice(deck)), one draw from the generator.

public static long DrawCard(Generator npRandom)

Parameters

npRandom Generator

The generator.

Returns

long

The card's value, 1 to 10.

Remarks

DrawHand(Generator)

Gymnasium's draw_hand: two cards, two draws.

public static List<long> DrawHand(Generator npRandom)

Parameters

npRandom Generator

The generator.

Returns

List<long>

A new list of the two cards, in draw order.

Remarks

DrawTable(Surface, long, long, long, string)

Gymnasium's draw_table: the felt, the dealer's label and face-up value, the face-up card and the hidden one, the player's label and total centred in big digits, and the usable-ace label when there is one.

public static void DrawTable(Surface surface, long playerSum, long dealerCardValue, long usableAce, string dealerCard)

Parameters

surface Surface

The surface drawn on, at least 384x376 for the whole table.

playerSum long

The player's total.

dealerCardValue long

The dealer's face-up value (an ace is 1).

usableAce long

Non-zero to show the usable-ace label.

dealerCard string

The face-up card's image name, face then suit ("KS", "AH", "7C").

Remarks

Exceptions

FileNotFoundException

Thrown for a card no image exists for (a ten named "10S"), or a negative number's minus sign, where pygame raises its own FileNotFoundError.

IsBust(IReadOnlyList<long>)

Gymnasium's is_bust: whether the hand's total is over 21.

public static bool IsBust(IReadOnlyList<long> hand)

Parameters

hand IReadOnlyList<long>

The cards.

Returns

bool

true for a bust.

Remarks

IsNatural(IReadOnlyList<long>)

Gymnasium's is_natural: sorted(hand) == [1, 10], an ace and a ten as the only two cards.

public static bool IsNatural(IReadOnlyList<long> hand)

Parameters

hand IReadOnlyList<long>

The cards.

Returns

bool

true for a natural blackjack.

Remarks

Render()

Renders the table (any render mode but human returns the frame); without a render mode, warns as Gymnasium does and returns nothing.

public override RenderResult Render()

Returns

RenderResult

human: nothing. Any other mode: the (376, 384, 3) uint8 frame, a new array the caller owns.

Remarks

Exceptions

AssertionError

Thrown without a render mode when the env has no spec (assert self.spec is not None).

AttributeError

Thrown before the first reset (no player), after the screen was created; or for hands injected before it (no face-up card's face and suit).

IndexError

Thrown when an injected dealer's hand is empty.

FileNotFoundException

Thrown for a total or face-up value whose digits have no image (a negative number).

KeyError

Thrown in human mode when metadata["render_fps"] was removed.

DependencyNotInstalled

Thrown on the first human render when no viewer factory is set (DR-20).

Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)

Deals a game: reseeds the generator when a seed is given, draws the dealer's hand, then the player's, then the face-up card's suit and, for a ten, its face. Renders in human mode.

public override ResetResult<object?[]> Reset(BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)

Parameters

seed BigInteger?

The seed of a fresh Generator(PCG64(SeedSequence(seed))), or null to keep the generator.

options IReadOnlyDictionary<string, object>

Ignored, as in Gymnasium.

Returns

ResetResult<object[]>

The observation (three new 0-d int64 arrays the caller owns) and an empty info.

Remarks

Exceptions

Error

Thrown for a negative seed, with Gymnasium's message.

DependencyNotInstalled

Thrown in human mode by the first render when no viewer factory is set (DR-20).

Score(IReadOnlyList<long>)

Gymnasium's score: the hand's total, or 0 for a bust.

public static long Score(IReadOnlyList<long> hand)

Parameters

hand IReadOnlyList<long>

The cards.

Returns

long

The score.

Remarks

Step(NDArray)

Plays the action: a hit (true) draws a card for the player and ends the game on a bust (-1.0); a stick (false) draws the dealer's cards while their total is under 17 and scores the game, with Sab's automatic natural win and Natural's 1.5. Renders in human mode.

public override StepResult<object?[]> Step(NDArray action)

Parameters

action NDArray

0 (stick) or 1 (hit): a 0-d integer array, or through the untyped step a .NET integer or bool.

Returns

StepResult<object[]>

The observation (three new 0-d int64 arrays the caller owns), the reward, whether the game ended, truncated=False, and an empty info.

Remarks

Exceptions

AssertionError

Thrown for an action Discrete(2) does not contain (Gymnasium's bare assert).

AttributeError

Thrown before the first reset: 'BlackjackEnv' object has no attribute 'player' for a hit, 'dealer' for a stick.

IndexError

Thrown when an injected dealer's hand is empty (list index out of range).

DependencyNotInstalled

Thrown in human mode by the first render when no viewer factory is set (DR-20).

SumHand(IReadOnlyList<long>)

Gymnasium's sum_hand: the hand's total, a usable ace counted as 11.

public static long SumHand(IReadOnlyList<long> hand)

Parameters

hand IReadOnlyList<long>

The cards.

Returns

long

The total.

Remarks

UsableAce(IReadOnlyList<long>)

Gymnasium's usable_ace: 1 when the hand holds an ace that can count as 11 without busting, else 0.

public static long UsableAce(IReadOnlyList<long> hand)

Parameters

hand IReadOnlyList<long>

The cards.

Returns

long

1 or 0 (Python's int of the test).

Remarks