feat: get-set game state

[S1M0N38]

Summary

Implement a new set_game_state function in src/lua/utils.lua that can apply a simplified game state (output from get_game_state) back to the game. This will enable game state serialization/restoration for testing, debugging, and development workflows.

Current State

We currently have utils.get_game_state() in src/lua/utils.lua that extracts and simplifies the complex game state object G into a clean, serializable format. The function returns:

{
  state = G.STATE,
  game = { -- simplified G.GAME fields
    dollars = ...,
    chips = ...,
    current_round = { ... },
    -- ... other key fields
  },
  hand = { ... },           -- simplified G.hand
  jokers = { ... },         -- simplified G.jokers  
  consumables = { ... },    -- simplified G.consumables
  shop_jokers = { ... },    -- simplified G.shop_jokers
  shop_vouchers = { ... },  -- simplified G.shop_vouchers
  shop_booster = { ... },   -- simplified G.shop_booster
}

Proposed Solution

Create a new utils.set_game_state(game_state) function that:

1. Takes a simplified game state (the output format of get_game_state)
2. Applies values to the actual game state by setting fields in G.GAME, G.hand, G.jokers, etc.
3. Handles nested field mapping properly (e.g., game_state.game.dollars → G.GAME.dollars)
4. Validates input structure and provides meaningful error messages
5. Is safe and non-destructive - only sets fields that exist in the input

Use Cases

1. Testing Workflow

-- Reach a specific game state manually or using debugplus
local saved_state = utils.get_game_state()
-- Save to JSON file for test fixtures

-- In tests: load and apply saved state
utils.set_game_state(test_fixture_state)
-- Run test scenarios from known state

2. Development and Debugging

• Save interesting game states during development
• Reproduce specific scenarios for bug investigation
• Create standardized test scenarios for bot development

3. Consistency Validation

local original_state = utils.get_game_state()
utils.set_game_state(original_state)
local restored_state = utils.get_game_state()
-- Assert: original_state == restored_state

Implementation Requirements

Function Signature

---Applies a simplified game state back to the game
---@param game_state G The simplified game state (from get_game_state)
---@return boolean success, string? error_message
function utils.set_game_state(game_state)

Key Field Mappings

The function should handle these main mappings:

• game_state.game.* → G.GAME.* (dollars, chips, round, etc.)
• game_state.hand.* → G.hand.* (cards, config)
• game_state.jokers.* → G.jokers.* (cards, config)
• game_state.consumables.* → G.consumables.*
• game_state.shop_jokers.* → G.shop_jokers.*
• game_state.shop_vouchers.* → G.shop_vouchers.*
• game_state.shop_booster.* → G.shop_booster.*
• game_state.state → G.STATE

Error Handling

• Validate input structure before applying changes
• Return success/failure status with descriptive error messages
• Handle missing or invalid fields gracefully
• Preserve game state if restoration fails

Safety Considerations

• Only set fields that exist in the input (don't clear existing fields)
• Validate that target game objects exist (G.GAME, G.hand, etc.)
• Consider read-only or computed fields that shouldn't be set directly
• Handle complex nested structures carefully

Testing Strategy

1. Round-trip consistency test:

   local original = utils.get_game_state()
   utils.set_game_state(original)
   local restored = utils.get_game_state()
   assert(original == restored)

2. Partial state restoration: Test with subsets of the full state

3. Error handling: Test with malformed or incomplete input

4. Edge cases: Empty states, missing fields, invalid values

Benefits

• Enhanced Testing: Create reproducible test scenarios from saved game states
• Debugging: Quickly reproduce specific game situations for investigation
• Development: Accelerate bot development by testing against known states
• State Management: Foundation for save/load functionality if needed in future

Implementation Notes

• Consider the extensive field mapping needed (reference get_game_state for structure)
• Some fields might be computed or derived - identify which are safe to set directly
• Card objects have complex nested structures that need careful handling
• The function should be robust enough to handle partial state restoration

Acceptance Criteria

• utils.set_game_state(game_state) function implemented
• Handles all major game state categories (game, hand, jokers, consumables, shop areas)
• Returns success/failure status with error messages
• Passes round-trip consistency tests
• Includes proper input validation and error handling
• Documented with usage examples and field mappings

This issue was generate by claude. We need to double check it