Poggy Chess

Overview#

Poggy Chess puts chess and checkers tables in your world. The script places the table, the board, both chairs and the pieces itself, so nothing has to be built into the map. Characters walk to a chair and sit down the way the game's own people do, then play on a real board of props.

Players can play each other, or sit alone and play a computer opponent that takes the other chair. Two players can put money on a game, and the script holds both stakes until the game ends. Every game is saved, so players can look back at any of them move by move.

It comes with a marble chess set, a separate resource called poggy_chess_props. See Configuration for how it is used.

• Chess with every rule: castling, en passant, promotion, check, and draws by stalemate, repetition, the fifty-move rule and too few pieces to mate.
• Checkers in American, Russian, Brazilian and Pool rules, or house rules picked at the table. The rules stay on screen all game.
• A computer opponent: seven chess levels from Beginner to Grandmaster, and three checkers levels. Its moves are chosen on the server.
• A chess clock for both games, picked by the player who sets up the game.
• Wagers between players, held safely. Walking away loses the game, so nobody can dodge paying.
• Elo ratings and a leaderboard, one for chess and one for checkers, per character.
• My record: every game a character has played, with filters and a move-by-move review.
• Unfinished games are saved and can be picked up later. Other players nearby can watch a game.
• Five tables ready to use. Add your own in /poggy or config.lua.
• Every setting in the /poggy settings hub, and every line of text in translations.lua.

Requirements#

• A RedM server running VORP Core, RSG Core or QBCore RedM.
• poggy_core 0.23.0 or newer. It connects the script to your framework.
• oxmysql.
• poggy_chess_props for the marble set. It comes with Poggy Chess. Without it the game's own wooden set is used.
• For the three strongest chess levels, the server needs to reach chess-api.com over the internet. If it cannot, those levels use the server's own engine instead, so games never stop.

Installation#

1. Download poggy_chess and poggy_chess_props from your Cfx portal.
2. Put both folders in your server's resources folder.
3. Add them to your server.cfg after oxmysql and poggy_core, with the props before the script:

   ensure oxmysql
   ensure poggy_core
   ensure poggy_chess_props
   ensure poggy_chess

4. Restart the server. The database tables are created on the first start. There is nothing to import.
5. Go to one of the five ready-made tables (they are on the map) or add your own (see Configuration).

The script makes three database tables:

Configuration#

Every setting can be changed in game in the settings hub: type /poggy and pick Chess & Checkers. The same settings are in config.lua. Every line players read is in translations.lua. Both files stay readable, so you can edit them.

The marble chess set

The marble set is a black and white marble board with white and black marble pieces, each one veined differently. It lives in its own resource, poggy_chess_props, which comes with Poggy Chess. It is also sold on its own. Its own page is Poggy Chess Props.

How Poggy Chess uses it:

• It is found automatically. When poggy_chess_props is running, every table uses the marble board and pieces. There is nothing to set up.
• One switch turns it off. In /poggy → Chess & Checkers → Tables, turn off Marble board and pieces (Config.MarbleSet, on by default) to go back to the game's wooden set.
• Without the props, the wooden set is used. If poggy_chess_props is not running, the script uses the game's own wooden board and pieces, whatever the switch says. Nothing breaks.
• Checkers is played on the marble board too, with the game's own red and black chips.
• If the marble models have not loaded on a player's game within 20 seconds, that player gets the wooden set until poggy_chess restarts. A table is never held up waiting for them.

The prop settings under Advanced (Board prop, Chess piece props) are only used when the marble set is off.

Tables

Each table is one row in Tables (Config.Tables). Five ship ready to use: Blackwater Courtyard, Saint Denis Saloon, Rhodes Saloon, Armadillo Saloon and Sisika Prison.

1. Stand where the middle of the table should be, facing the way the white chair should face.
2. Open /poggy → Chess & Checkers → Tables, and press Add table.
3. Give it an Id (letters, numbers and underscores). It is saved with every game played there, so do not change it once games have been played.
4. Give it a Name. Players see it on the prompts and table screens.
5. On Position, press use my position. On Heading, use your heading. At heading 0 the white chair is on the east side.
6. Save, then restart the script.

Each table also has Show map blip, Blip icon, Blip colour and Blip size. Turning the blip off hides the table from the map; it still works. To remove a table, delete its row. Its past games stay in everyone's record.

Games and the clock

The computer opponent

These are on the hub tab for the computer opponent.

Each difficulty is one row in Chess levels or Checkers levels, and you can change, add or remove rows.

• Chess: Beginner, Novice, Casual and Club player play on the server's own engine. The easier ones make deliberate slips (Mistake chance) so they can lose. Advanced, Expert and Grandmaster ask Stockfish at chess-api.com, aiming at a Target winning chance, so even these can be beaten. If chess-api.com cannot be reached in time, the server's own engine plays that move.
• Checkers: Easy, Medium and Hard, always on the server's own engine. Looseness lets the easier levels pick among good moves instead of always the best.
• Draws from move and Takes a draw up to decide when the computer opponent accepts a draw offer. Easier levels take draws readily; the hardest rarely do.
• The name shown for a level comes from level_<id> in the NUI block of translations.lua. A new level without a line there shows its id.

Wagers

Sitting, death and keys

Records and ratings

Rating changes apply from the next game. To work every rating out again under new settings, run /chesstable rerate.

Screen and sound

Language and advanced

• Language (Config.Language, default en) picks the block of translations.lua to use. Only English ships. To add a language, copy the en block, give it a new key, and translate it. Missing lines fall back to English. Keep every %s and %d.
• The Advanced tab holds the table, board, chair and piece props, the layout of the board, the cameras and the move animation. Change these only if you use other props.
• Debug output (off) prints what the script is doing to the server console. Leave it off on a live server.

Commands#

Keys at the table

Permissions#

Playing needs no permission: anyone can sit at a table.

/chesstable works for the server console and for admins. "Admin" is decided by poggy_core from your framework's own groups (admin, superadmin, god, owner, headadmin, developer). There is no separate ACE permission for it. For anyone else the command does nothing.

Who can open and change the settings in /poggy is set in poggy_core.

Using it in game#

Starting a game

1. Walk up to a chair and press G to sit. One chair is the White / Red side, the other the Black side.
2. The first player seated chooses the game: chess or checkers, the checkers variant, the clock and any wager.
3. To play another player, they sit in the other chair and are invited. They see the rules, the clock and the wager before they accept.
4. To play the computer opponent, sit alone and pick a level. It takes the other chair and plays the other colour, so a player in the black chair plays black and it moves first.

Playing

• Click a piece, then where it goes, on the table or on the small board on screen. G picks the square under the mouse.
• In checkers, a capture is picked one landing square at a time, so a capture that can go two ways is the player's choice. Pieces that must capture are ringed.
• The screen shows a move list, the rules, both players' ratings and, when a clock is used, both clocks. Against the computer opponent there are hints and, in chess, an evaluation bar.
• Other players within the show distance see the game on the table and can watch.

Wagers

• When the other player accepts, the stake is taken from both at once. If either cannot pay, nothing is taken and the game does not start.
• The winner gets both stakes. A draw, or a game that ends with no result (a death with abandon, an admin reset), returns each player their own.
• Standing up or leaving the server during a wagered game loses it, and the stake with it.
• If the server restarts during a wagered game, both stakes are returned. A player who is offline is paid the next time they are on.

The clock

• A time is written minutes+seconds: 5+3 is 5 minutes each, plus 3 seconds after each of your moves.
• The clocks start with the first move. A player whose time runs out loses. In chess it is a draw instead when the other side has too little left to checkmate.
• The server keeps the time, so a slow connection cannot win a player extra time.

Leaving and saved games

• Standing up from a game without a wager saves it, with the clocks stopped. Pick it up again from the start menu, sitting in the same chair.
• Games against the computer opponent are saved the same way.

My record and the leaderboard

• My record shows every game the character has played, with wins, draws and losses, opponents, filters for chess, checkers and games against the computer opponent, and a move-by-move replay of any game.
• Only finished games between two players are rated. Games against the computer opponent never change a rating. All checkers variants share one checkers rating.
• The Leaderboard tab lists players by rating once they have played enough rated games.

Troubleshooting#

The tables have the wooden set, not the marble one

Check that poggy_chess_props is in your resources and is started before poggy_chess in server.cfg, and that Marble board and pieces is on. If a player's game could not load the marble models within 20 seconds, that player gets the wooden set until poggy_chess restarts, and their F8 console shows a line saying so.

Players crashed when I restarted the props

Never start, stop or restart poggy_chess_props while players are in. Add it, remove it or update it with a full server restart.

I added a table but it is not there

Restart the script after saving a new table. Tables and pieces appear only within the Show distance (20 m), and only once a character is in the world, never on the character screen.

A game is stuck

Run /chesstable to see every table, then /chesstable reset <table id>. The game ends with no result, any wager goes back to both players, and both are stood up.

/chesstable does nothing

Your character is not an admin in your framework. Use the server console, or give yourself an admin group (see Permissions).

The strongest chess levels feel weaker than they should

They ask chess-api.com for moves. If your server cannot reach it within Stockfish wait (4000 ms), the server's own engine plays that move instead. Check that your host allows the server to make outgoing web requests.

A player was stood up in the middle of a game

They were more than Stand-up distance (8 m) from the table, for example teleported or dragged. That counts as leaving the game.

A player says they never got their wager back

If they were offline when it was returned, it waits in poggy_chess_payouts and is paid when they are next online (checked every 120 seconds). A row with paid_at filled in has been paid.

Characters sit too high, too low or facing the wrong way

Adjust Scenario height and Scenario turn under Sitting & keys (Advanced settings).

Updating#

Poggy Chess updates through poggy_core's updater. Your config.lua and translations.lua are merged, so new settings arrive with their defaults and your values stay.

• poggy_chess_props does not update through poggy_core. A new version of it comes as a new download from your Cfx portal. Install it with a full server restart.
• Keep each table's Id the same. Games are saved against it.
• Coming from 1.x: the old games table is extended in place. Old games keep their results and can still be reviewed. Records are now kept per character.