QR Codes

Beginner · 12 min read

Overview

QR codes are two-dimensional barcodes that smartphones and tablets can scan instantly using their camera. Adding QR codes to your cards lets players quickly access digital content: rules explanations, companion app links, video tutorials, or online card databases, by pointing their phone at the card.

Chitmunk generates QR codes directly on the canvas as a native element type. They render at full resolution during export, so they scan reliably even on small printed cards. With nine encoding modes, you can go far beyond simple URLs: encode WiFi credentials, calendar events, contacts, map locations, and more.

Adding a QR Code

To add a QR code to your card:

1. Click the Gen button in the tool strip (left edge of the canvas) and select QR Code from the Reference category. You can also press Ctrl+K to open the Command Palette and search for "QR Code".
2. A QR code generator element appears on the canvas with a default URL placeholder.
3. Select the QR code element and use the properties panel on the right to configure it. Double-click the element to open the full configuration modal.

The QR code updates in real time as you change its settings. You can move, resize, and position it like any other element on the canvas.

Choosing a Mode

The Mode dropdown in the properties panel controls what kind of data the QR code encodes. Each mode structures the data in a specific format so that QR reader apps know how to handle it: opening a browser, saving a contact, connecting to WiFi, and so on. Chitmunk handles all the formatting behind the scenes; you just fill in the fields.

When you switch modes, the properties panel updates to show the relevant input fields for that mode. All nine modes are available to all users.

QR Code Modes

URL

The default mode. Enter a web address and the phone opens it in a browser when scanned.

The properties panel shows a single URL field. Enter the full address including the protocol, for example, https://example.com/rules. Most QR reader apps will handle both http:// and https:// URLs, but https:// is recommended for security.

Board game uses: Link to a detailed rules explanation or FAQ page for a specific card. Point to your game's companion app download page or Kickstarter campaign. Encode a unique URL per card using CSV binding to create a digital lookup for every card in a collectible set.

Plain Text

Encode any raw text up to approximately 4,000 characters. When scanned, the QR reader app displays the text directly on screen, no browser, no internet connection required.

The properties panel shows a multiline Text field. Type or paste whatever text you want the scanner to see.

Board game uses: This mode shines for hidden information mechanics. Encode secret objectives, clue answers, plot twists, or character backstories that players reveal by scanning. In a mystery game, each suspect card could have a hidden alibi encoded in a QR code. In a legacy game, QR codes can deliver story text without spoiler-prone printed inserts. Escape room card games can use text QR codes for puzzle hints that only appear when a player decides to scan for help.

WiFi

Generate a QR code that automatically connects the scanning device to a WiFi network. No typing passwords: the phone joins the network with one scan.

The properties panel shows four fields:

• SSID: the network name (case-sensitive, must match exactly).
• Password: the network password. Leave blank for open networks.
• Encryption: choose WPA/WPA2 (most common), WEP, or None.
• Hidden: toggle this on if the network does not broadcast its SSID.

Board game uses: Put a WiFi QR code on demo table tent cards at conventions so playtesters connect instantly without asking for the password. Game cafes can print WiFi codes on their branded cards or coasters. If your game uses a companion app that needs internet access, a WiFi card in the box makes setup faster for game nights at a friend's house.

Contact (vCard)

Create a digital business card. When scanned, the phone offers to save the contact directly to the address book.

The properties panel shows fields for:

• Name: the contact's full name.
• Organization: company or studio name.
• Title: job title or role.
• Phone: phone number (include country code for international use, e.g. +1-555-123-4567).
• Email: email address.
• Website: URL for a website or portfolio.
• Address: physical address (street, city, state, zip).

You do not need to fill in every field. Only the fields you populate get encoded into the vCard.

Board game uses: Add your studio's contact info to card backs so playtesters and reviewers can save your details with a single scan. If you run a game design studio, put a vCard QR code on your business card-sized game credits insert. Convention demo copies can include your contact so interested publishers can reach you easily.

Email

Pre-fill an email so the scanner's phone opens their email app with the recipient, subject, and body already filled in. The user just hits send.

The properties panel shows three fields:

• To: the recipient email address.
• Subject: the email subject line.
• Body: the email body text.

Board game uses: Add a feedback QR code to prototype cards so playtesters can fire off impressions immediately. Pre-fill the subject with the game name and version number so feedback emails are easy to organize in your inbox. You can also use this for customer support, print a "Report a problem" QR code on your rulebook's card-sized quick reference.

SMS

Pre-fill a text message so the scanner's phone opens the messaging app with a number and message body ready to send.

The properties panel shows two fields:

• Number: the recipient phone number (include country code for international use).
• Body: the message text.

Board game uses: Set up an SMS voting system for party games, each card's QR code pre-fills a text with a vote code, and players scan to cast their vote. You can also use SMS codes for RSVP confirmations for game night events or to let playtesters quickly text feedback from a convention demo.

Phone

Encode a phone number. When scanned, the phone offers to dial the number. This is the simplest mode, just a number, nothing else.

The properties panel shows a single Number field. Include the country code for international numbers (e.g. +1-555-123-4567).

Board game uses: Phone mode is most useful for escape room and ARG (alternate reality game) components where players call a number to hear a recorded clue or unlock the next chapter. You can also use it as a quick support hotline link on your game's reference cards.

Location

Encode geographic coordinates so the scanner's phone opens a map app at a specific location.

The properties panel shows three fields:

• Latitude: the latitude in decimal degrees (e.g. 40.7128 for New York City).
• Longitude: the longitude in decimal degrees (e.g. -74.0060 for New York City).
• Label: an optional name that appears as the pin label on the map (e.g. "Game Night at The Board Room").

Board game uses: Location-based games and ARG components can encode real-world coordinates that players visit as part of gameplay. Print tournament or meetup venue locations on event cards so attendees can scan for instant directions. Geocaching-style games can put location QR codes on clue cards. You could even encode the coordinates of your favorite local game store on your card backs as a community recommendation.

Calendar Event

Create a calendar event that the scanner's phone offers to add to their calendar app. Includes full event details so nothing gets lost in translation.

The properties panel shows five fields:

• Title: the event name (e.g. "Board Game Night").
• Start: the start date and time.
• End: the end date and time.
• Location: where the event takes place (free text: an address, a room name, or a venue).
• Description: additional details about the event.

Board game uses: Print game night invites as cards with a scannable QR code, recipients scan to add the event to their calendar with all the details already filled in. Tournament organizers can create event cards for each round or session. Game launch events, Kickstarter live-play dates, and convention panel schedules all work well as calendar QR codes. If you distribute promo cards at a convention, adding a calendar event for your next demo session turns a promo into a reminder.

CSV Binding

QR codes become especially powerful when combined with CSV data merge. Use the {{Column Name}} template syntax in any text field across any mode to generate a unique QR code for every card in your deck.

CSV binding works in every text field across all nine modes: not just the main data field. You can bind the URL in URL mode, the SSID and password in WiFi mode, the recipient and subject in Email mode, the latitude and longitude in Location mode, and so on. Any field that accepts text also accepts {{Column}} template variables.

Here are a few examples:

• URL mode: Set the URL field to https://myapp.com/card/{{ID}}, each card links to its own unique page.
• Plain Text mode: Set the text to {{Secret Objective}}, each card reveals a different hidden objective when scanned.
• Email mode: Set the subject to Feedback on {{Card Name}}, each card's QR pre-fills the email subject with that card's name.
• Location mode: Set latitude to {{Lat}} and longitude to {{Lng}}, each card points to a different map location.
• Calendar Event mode: Set the title to {{Event Name}} and start time to {{Start Time}}, each card creates a different calendar event.

You can also mix static text with template variables in any field. For example, a WiFi password field set to game-{{Table Number}} produces a different password for each demo table.

Foreground & Background Colors

By default, QR codes render with black modules on a white background, the highest-contrast combination and the most reliable for scanning. You can change both colors to match your card's design:

• Foreground color: the color of the QR modules (the dark squares). Click the color swatch in the properties panel to pick any color.
• Background color: the color behind the modules. You can set this to transparent if your card background provides enough contrast.

A few guidelines for color choices:

• Maintain high contrast. QR readers rely on the difference between the foreground and background colors. Dark-on-light combinations (dark blue on white, black on cream) work best. Light-on-dark combinations (white on black) also work on most modern scanners.
• Avoid mid-tones. A gray foreground on a slightly lighter gray background will fail to scan. Keep the contrast ratio high.
• Test on a real phone. Colors that look fine on screen may not scan reliably when printed. Print a test card and try scanning with two or three different phones before committing to a color scheme.

Error Correction

QR codes have built-in redundancy that allows them to be scanned even if part of the code is damaged, smudged, or covered. The Error Correction dropdown in the properties panel lets you choose how much redundancy to include:

• L (Low), ~7% recovery. Produces the smallest, simplest QR code. Best when the code will be large and printed on smooth card stock with no risk of damage or obstruction.
• M (Medium), ~15% recovery. The default level and a good choice for most printed cards. Balances code density with resilience.
• Q (Quartile): ~25% recovery. Recommended when the QR code will be printed small (under 0.75 inches) or on textured, linen, or kraft card stock where surface texture can interfere with scanning.
• H (High), ~30% recovery. Maximum resilience, but produces the densest code. Use this when part of the QR code might be covered by a design element, a logo overlay, or wear and tear from heavy play.

Higher error correction levels add more data to the code, which makes it denser (more modules, smaller squares). For small QR codes, this tradeoff matters: a denser code is harder to scan at small sizes. If your QR code is 0.5 inches and you choose H-level correction, the individual modules may be too tiny for some phone cameras to resolve.

Sizing for Print

QR codes are always square. When you resize a QR code element, Chitmunk maintains a 1:1 aspect ratio automatically, dragging any corner or edge snaps to a square.

For reliable scanning on printed cards, follow these sizing guidelines:

• Minimum: 0.5 inches (12.7 mm) per side. This is the absolute floor for simple data (short URLs, phone numbers). Below this, many phone cameras struggle to resolve the individual modules.
• Recommended: 0.6 to 0.8 inches (15 to 20 mm) per side. This range works well for most modes and data lengths on standard card sizes like poker or tarot.
• Dense data: 0.8 to 1.0 inches (20 to 25 mm) per side. If you are encoding a vCard with many fields, a long calendar event description, or a WiFi password with special characters, give the code more room so the modules stay large enough to scan.

The relationship between data length and code density is straightforward: more data means more modules, and more modules in the same physical space means smaller squares. Keep the encoded data as short as practical, and give dense codes more room on the card.

Tips & Best Practices

• Keep data short. Shorter data produces a simpler QR code with larger modules, which is easier to scan at small print sizes. Use a URL shortener for long web addresses. In Text mode, keep the message concise. In vCard mode, only fill in the fields you actually need.
• Choose the right mode for the job. URL and Phone modes produce the smallest codes. Plain Text and WiFi are moderate. vCard and Calendar Event produce the largest codes. Pick the simplest mode that gets the job done.
• Test on real hardware. QR codes that scan perfectly on your monitor may behave differently when printed on card stock. Always test with a printed card and at least two different phone models.
• Add a quiet zone. QR codes need a margin of blank space around them (called the quiet zone) to scan reliably. Chitmunk includes this automatically, but if you position other design elements too close to the QR code, they can interfere. Leave at least a few pixels of breathing room on all sides.
• Consider offline players. URL mode requires an internet connection. If your game might be played offline, use Plain Text mode for information that should always be accessible.
• Use CSV binding for per-card codes. A single QR code element with {{Column}} bindings generates a unique code for every row in your CSV. This is far more efficient than placing a separate QR code image on each card manually.
• Label your QR codes. Players may not know what a QR code does just by looking at it. Add a small text label nearby: "Scan for rules", "Add to calendar", "Join WiFi", so players know what to expect before they scan.
• Use error correction wisely. M (Medium) is a good default. Only increase to Q or H if you have a specific reason: small code, rough card stock, or intentional partial obstruction. Higher correction makes the code denser, which can backfire at small sizes.

Common Use Cases by Mode

A quick reference for matching game design needs to QR code modes: