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
optionsBlackjackEnvOptionsThe options.
Exceptions
- ArgumentNullException
Thrown when
optionsis 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
renderModeRenderModeThe 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.naturalboolGymnasium's
natural: a winning natural blackjack pays 1.5 (ignored whensabis set).sabboolGymnasium's
sab: Sutton and Barto's rules, where a natural against a dealer without one wins outright.viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
renderModestringGymnasium's
render_mode: null,"human"or"rgb_array"(any other mode draws likergb_array, as in Gymnasium).naturalboolGymnasium's
natural: a winning natural blackjack pays 1.5 (ignored whensabis set).sabboolGymnasium's
sab: Sutton and Barto's rules, where a natural against a dealer without one wins outright.viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
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
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
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
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
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
Natural
Gymnasium's natural: whether a winning natural blackjack pays 1.5. Read at every stick.
public bool Natural { get; set; }
Property Value
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
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
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
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
Reference: gymnasium/envs/toy_text/blackjack.py.
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
Returns
- double
1.0, -1.0 or 0.0 (also for a NaN, which compares neither way).
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.
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
actionobjectThe 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
npRandomGeneratorThe generator.
Returns
- long
The card's value, 1 to 10.
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.
DrawHand(Generator)
Gymnasium's draw_hand: two cards, two draws.
public static List<long> DrawHand(Generator npRandom)
Parameters
npRandomGeneratorThe generator.
Returns
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.
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
surfaceSurfaceThe surface drawn on, at least 384x376 for the whole table.
playerSumlongThe player's total.
dealerCardValuelongThe dealer's face-up value (an ace is 1).
usableAcelongNon-zero to show the usable-ace label.
dealerCardstringThe face-up card's image name, face then suit (
"KS","AH","7C").
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.
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 ownFileNotFoundError.
IsBust(IReadOnlyList<long>)
Gymnasium's is_bust: whether the hand's total is over 21.
public static bool IsBust(IReadOnlyList<long> hand)
Parameters
handIReadOnlyList<long>The cards.
Returns
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.
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
handIReadOnlyList<long>The cards.
Returns
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.
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
Reference: gymnasium/envs/toy_text/blackjack.py.
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
seedBigInteger?The seed of a fresh
Generator(PCG64(SeedSequence(seed))), or null to keep the generator.optionsIReadOnlyDictionary<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
Reference: gymnasium/envs/toy_text/blackjack.py.
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
handIReadOnlyList<long>The cards.
Returns
- long
The score.
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.
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
actionNDArray0 (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
Reference: gymnasium/envs/toy_text/blackjack.py.
Exceptions
- AssertionError
Thrown for an action
Discrete(2)does not contain (Gymnasium's bareassert).- 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
handIReadOnlyList<long>The cards.
Returns
- long
The total.
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.
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
handIReadOnlyList<long>The cards.
Returns
- long
1 or 0 (Python's
intof the test).
Remarks
Reference: gymnasium/envs/toy_text/blackjack.py.