Crafty Cards

Changelog

This project follows Semantic Versioning.

Pre-publication review note: the 1.0.0 section describes an earlier feature set and is not a current acceptance report for every supported version. For the current support matrix and evidence, see docs/open-source/README.md and docs/自动化验收.md in the repository.

[Unreleased]

Multiple loaders and Minecraft versions

• Shared gameplay, HUD, models, and resources moved into common/. NeoForge, Fabric, and Forge each supply their own registration, networking, events, client rendering, and resource-pack integration.
• Compatibility extends through Minecraft 1.21.11. There is no target Forge release for 1.21.2. Each target is built independently and run through an automated three-client match. Refer to the latest locally generated acceptance dashboard for results. Card readability, full-screen HUD proportions, configuration text, and actual audio still require manual review.

Added

• Two new BGM cues for endgame play and a rocket (bgm_clutch and bgm_rocket). During play, a player with three or fewer cards selects bgm_clutch; a rocket as the last play selects bgm_rocket until the next lead. The rocket cue takes priority when both apply. Older sound packs fall back through bgm_rocket → bgm_clutch → bgm_playing when a cue has no file. The sound-pack maker's key list and trigger descriptions were updated: 7 effects + 6 BGM cues + 48 hand-type voice lines = 61 audio keys.
• chipsRequired in server.json defaults to enabled. Turning it off makes tables no-stakes games: no chip item or inventory threshold is required, no stake is collected, and settlement transfers no items. Three players can join by right-clicking the table. The gameplay settings screen has a matching switch and hides the inactive stake and entry threshold. The client learns the rule from chipRequired = 0 in the server snapshot, which also works with dedicated servers.

Changed

• Sound packs are the only source of mod audio. The Sound Effects and Voice, Hand-Type Voice, Background Music, and individual audio-key settings screens were removed. In-game settings now only enable or disable mod audio, set its volume, and select a sound pack. Edit files and weights with the pack maker. Legacy localFiles and weights configuration entries are ignored, and config/crafty_cards/sounds/ is no longer scanned. BGM channel and vanilla-music ducking options remain in sounds.json for manual editing and require a restart. /craftycards sounds opens the Sound Packs page.

Fixed

• Hand-type voice lines were silent because registered sound IDs did not match resource-pack keys. Events used voice_<key> (for example, crafty_cards:voice_dan1), while generated sounds.json used <key> (dan1). All 48 voice lines consequently lacked matching resources and did not fall back to vanilla sounds. Registration and generation now share CustomAudio.soundId(). ClientSounds.libraryHas() checks the loaded sound library, falls back when an event is missing, and logs one warning. Tests cover the mapping, generated JSON, and registered events.
• Saving server.json wrote defaults instead of current settings. save() serialized new Data() rather than the active configuration. Manual edits and in-game saves reverted to defaults on restart. It now serializes snapshot(). Literal defaults remain for missing fields in older files; an absent chipsRequired still means chips are required. Stake-related GameTests explicitly state their prerequisites.
• Four cards of one rank can no longer stand in for a triple. A hand such as 3333 444 55 6 was incorrectly accepted as an airplane with pairs because the wing check counted ranks instead of cards. Every pair wing must now contain exactly two cards. Unit tests cover classification and rejection through the play path.
• The three bottom cards are no longer sent during bidding. The snapshot previously included getDipai() even though the HUD hid it, so a modified client could inspect the cards before bidding. They are sent only during play, when they are public information.
• Settlement pays from the stake pool before collecting from inventory. Returning stakes before collecting payment had allowed a losing player to move chips out of inventory and avoid paying. The original staked items, including their components, now pay first; inventory covers any remainder.
• Repeatedly toggling spectator mode no longer postpones idle cleanup. Only an active player's actions count as activity.
• Bid options that do not exceed the current bid are dimmed in the HUD. Selecting one gives an immediate local explanation instead of only a server rejection.

[1.0.0] — Initial release

Dou Dizhu gameplay

• Complete three-player online flow: craft a table, place it, join, bid for landlord, play cards, and settle the game.
• Server-authoritative rules for singles, pairs, triples, triple with one or two cards, straights, consecutive pairs, airplanes with wings, four with two single cards or pairs, bombs, and rockets.
• Bids of pass, 1, 2, or 3 points; redeal after three rounds without a bid.
• Scoring based on the bid and multipliers: each bomb or rocket doubles the score, as does a spring or reverse spring.
• In this original feature set, players declared a chip item from their main hand, subject to a server allowlist. One item per player entered the stake pool; settlement transferred items without creating or destroying value, preserved item components, and refunded stakes if the game ended early.
• The host could configure the entry stake in server.json; the entry threshold scaled with it.

Interaction

• A HUD overlay kept the world around the table visible.
• In this original feature set, holding a placeholder Dou Dizhu card item expanded the hand; switching items hid the hand without leaving the game.
• Mouse wheel for card focus or bids, left click to confirm a card, and right click on the table to play or pass. Cards could be preselected out of turn.
• Players could move freely after joining, without being bound to seats.
• Nearby players could opt into read-only spectating with Shift + right click.

In-world rendering

• Fanned hand cards, raised selected cards, and a yellow focus outline that follows each card's angle.
• Other players' hands follow their positions and view directions. Faces point toward the holder, with cards layered from left to right.
• Played cards appear on the table with visible stacking thickness.
• Spectators behind a player can see that player's card faces. The server sends visible card data separately to each recipient to prevent cheating.

Audio and sound packs

• No audio files were bundled in the mod JAR. Sound effects and BGM came from separately installed sound packs.
• The original release described 59 audio keys: 7 effects, 4 BGM cues, and 48 hand-type voice lines.
• A key could reference multiple files with weights; Minecraft's sound engine selected among them. The original in-game editor supported per-file weights and previews.
• Hand-type voice lines took priority over generic play effects.
• tools/soundpack_maker.py provided a tkinter GUI and --cli mode to convert MP3, WAV, or FLAC to Ogg, assign files to keys, set weights, and generate pack.json.
• The original maker showed a three-step workflow, help text, trigger descriptions, and weight guidance; preview opened a file with the system player.
• The original in-game settings could also assign individual files from config/crafty_cards/sounds/ and mix them with sound-pack files. These editor and individual-file features were subsequently removed as described under Unreleased.

Configuration

• Client rendering settings in visual.json, reloadable with /craftycards reload.
• Client audio settings in sounds.json and server gameplay settings in server.json.
• The original in-game settings used a home page with separate sound, music, sound-pack, gameplay, and rendering pages. Layout calculations moved into the tested pure-function ConfigLayout module to prevent overlap or clipping at different window sizes.
• The original audio pages shared an edit session and prompted before discarding unsaved changes. Source labels, per-key weights, previews, and individual-file editing were available at the time; those audio-editing pages were later removed.
• Rendering controls included hand size and spacing, fan angle, world-hand distance and height, played-card scale, and floating-chip height.

Reliability

• Disconnecting, breaking the table, or leaving cleaned up the session and returned items as appropriate.
• On an in-game leave, the departing player received a session-closed snapshot before the seat was cleared, so the client did not remain stuck in the game HUD.
• Cards and stakes were reclaimed before clearing a seat; disbanding skipped empty seats to avoid lost stakes and server-side null-pointer errors.
• Idle sessions expired automatically. The server validated join distance, turns, card ownership, and legal hand types.
• Tests and the JAR task prevented .ogg files from being bundled in mod resources.

Notes

• Only content needed for Dou Dizhu remained registered. Prototype poker tables, chips, dice, and bar stools were no longer registered.
• Prototype blocks already placed in old saves, including poker tables and bar stools, became air because those blocks were removed.