Contributing Guide

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/kasimeka/balatro-typist-mod/llms.txt

Use this file to discover all available pages before exploring further.

​

Welcome Contributors!

​

Ways to Contribute

​

Reporting Bugs

1. Check if the issue already exists in GitHub Issues
2. Verify you’re using a supported Balatro version (1.0.1n or 1.0.1o)
3. Test with only Typist installed (disable other mods) to rule out conflicts

**Describe the bug**
A clear description of what's wrong.

**To Reproduce**
1. Go to '...'
2. Press '...'
3. See error

**Expected behavior**
What should happen instead.

**Environment:**
- Balatro Version: [e.g., 1.0.1o]
- OS: [e.g., Windows 11, macOS 14.2, Linux]
- Keyboard Layout: [qwerty/dvorak/workman]
- Other Mods Installed: [list them]
- Custom Overrides: [yes/no, and paste contents if yes]

**Additional context**
Screenshots, error messages, or any other relevant details.

​

Suggesting Features

• Describe the use case and why it would be valuable
• Consider how it fits with Typist’s keyboard-driven philosophy
• Propose potential keybindings (if applicable)
• Be open to discussion and iteration

• Deck selection keybinds (hjkl for deck and stake selection)
• Half-keyboard layouts for one-hand operation
• Menu navigation keybinds
• Redesigned arcana and spectral packs UX
• Controller UI for displaying keybind hints

​

Improving Documentation

• Fixing typos or unclear explanations
• Adding examples or tutorials
• Improving the wiki
• Creating video guides or screenshots

​

Code Contributions

​

Getting Started

1. Fork the Repository Click the “Fork” button on GitHub
2. Clone Your Fork
   git clone https://github.com/YOUR_USERNAME/balatro-typist-mod.git
   cd balatro-typist-mod
   
3. Set Up Development Environment
   • Install Balatro (obviously!)
   • Install the Lovely injector
   • Symlink your cloned repo to the Mods directory:
     # Windows (cmd as admin)
     mklink /D "%AppData%\Balatro\Mods\balatro-typist-mod" "C:\path\to\your\clone"
     
     # macOS/Linux
     ln -s /path/to/your/clone "$HOME/Library/Application Support/Balatro/Mods/balatro-typist-mod"
     
4. Create a Branch
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   

​

Code Style Guidelines

line_endings = "Unix"
column_width = 100
indent_type = "Spaces"
indent_width = 2
quote_style = "AutoPreferDouble"
call_parentheses = "NoSingleTable"
collapse_simple_statement = "ConditionalOnly"

[sort_requires]
enabled = true

• Use 2 spaces for indentation (not tabs)
• Maximum 100 characters per line
• Prefer double quotes for strings
• Unix-style line endings (LF, not CRLF)
• Sort require statements
• Omit parentheses for single table argument function calls

# Install StyLua
cargo install stylua
# or use a pre-built binary from GitHub releases

# Format your code
stylua .

# Check what would change without modifying files
stylua --check .

​

Project Structure

balatro-typist-mod/
├── mod/
│   ├── init.lua              # Entry point, settings initialization
│   ├── layout.lua            # Keyboard layout definitions and keybindings
│   ├── entrypoint.lua        # Main mod initialization
│   ├── state-handlers.lua    # Game state-specific logic
│   ├── cardarea-handler.lua  # Card area interaction logic
│   ├── cardarea-ext.lua      # Card area extensions
│   ├── hand.lua              # Hand manipulation
│   ├── handutils.lua         # Hand utility functions
│   ├── settings-page.lua     # In-game settings UI
│   └── smods.lua             # Steamodded integration
├── lib/
│   ├── tblutils.lua          # Table utility functions
│   └── log.lua               # Logging utilities
├── compat/
│   ├── init.lua              # Compatibility layer initialization
│   ├── debugplus.lua         # DebugPlus compatibility
│   ├── multiplayer.lua       # BalatroMultiplayer compatibility
│   ├── taikomochi.lua        # Taikomochi compatibility
│   └── fhotkey.lua           # FlushHotkeys compatibility
└── lovely.toml               # Lovely injector configuration

• mod/layout.lua - Add or modify keybindings here
• mod/state-handlers.lua - Add handlers for different game states
• compat/*.lua - Add compatibility for other mods

​

Development Workflow

1. Make Your Changes
   • Write clean, commented code
   • Follow the existing code style
   • Test thoroughly in-game
2. Test Your Changes
   • Test with all three keyboard layouts (qwerty, dvorak, workman)
   • Test with and without other compatible mods
   • Test edge cases (e.g., what happens with 10+ jokers?)
   • Verify nothing breaks in different game states
3. Format Your Code
   stylua .
   
4. Commit Your Changes Write clear, descriptive commit messages:
   # Good commit messages
   git commit -m "Add keybinding for deck selection in new run menu"
   git commit -m "Fix card selection bug with more than 9 cards"
   git commit -m "Improve performance of card hover detection"
   
   # Avoid vague messages
   git commit -m "Fix bug"  # Too vague
   git commit -m "Update code"  # Not descriptive
   
5. Push to Your Fork
   git push origin feature/your-feature-name
   

​

Pull Request Process

1. Create a Pull Request
   • Go to your fork on GitHub
   • Click “New Pull Request”
   • Select your branch
   • Write a clear description of your changes
2. PR Description Template
   ## Description
   Brief description of what this PR does.
   
   ## Changes
   - Added X feature
   - Fixed Y bug
   - Improved Z performance
   
   ## Testing
   - Tested on Balatro 1.0.1o
   - Tested with qwerty/dvorak/workman layouts
   - Tested with Steamodded, DebugPlus, etc.
   
   ## Related Issues
   Closes #123
   Related to #456
   
   ## Screenshots/Videos
   (If applicable)
   
3. Code Review
   • Be responsive to feedback
   • Make requested changes promptly
   • Discuss concerns constructively
4. Merge Once approved, a maintainer will merge your PR. Congratulations!

​

Coding Best Practices

• Backwards Compatibility: Don’t break existing functionality or keybindings
• Performance: Avoid expensive operations in tight loops (especially in card rendering)
• Error Handling: Gracefully handle edge cases
• Comments: Explain why, not just what
• Modularity: Keep functions focused and reusable
• Testing: Test edge cases, not just the happy path

​

Getting Help

​

Join the Community

• Discord: Join the Balatro Discord and find Typist’s thread
• GitHub Discussions: Ask questions on GitHub
• Code Review: Don’t hesitate to ask for feedback on your approach before implementing

​

Learning Resources

• Balatro Modding: Study other Balatro mods for examples
• Lovely Injector: Read the Lovely documentation
• Lua Reference: Lua 5.1 Reference Manual (Balatro uses Lua 5.1)
• LÖVE Framework: LÖVE wiki (Balatro is built on LÖVE)

​

License

• The project remains free and open-source
• Derivatives must also be open-source
• Users have the freedom to use, modify, and distribute the code

​

Recognition

• The GitHub contributors list
• The project README (for significant contributions)
• Commit history (your commits remain attributed to you)

​

Questions?

• Ask in the Discord thread
• Open a GitHub Discussion
• Comment on a related issue