|
1 | | -# Welcome to your Lovable project |
| 1 | +# BalatroBench |
2 | 2 |
|
3 | | -## Project info |
| 3 | +A community-driven benchmark platform for evaluating Large Language Models' strategic performance in Balatro through intelligent tool-calling and decision-making. |
4 | 4 |
|
5 | | -**URL**: https://lovable.dev/projects/e725613f-1a63-446f-a2ba-256bc91b759f |
| 5 | +## 🎯 What is BalatroBench? |
6 | 6 |
|
7 | | -## How can I edit this code? |
| 7 | +BalatroBench provides a standardized way to evaluate how well different AI models can play Balatro, the popular poker-inspired roguelike card game. The benchmark tests strategic thinking, decision-making, and tool-calling capabilities across different LLM models. |
8 | 8 |
|
9 | | -There are several ways of editing your application. |
| 9 | +## 🚀 Quick Start |
10 | 10 |
|
11 | | -**Use Lovable** |
| 11 | +This is a **static website** that works with any web server or GitHub Pages. No build process required! |
12 | 12 |
|
13 | | -Simply visit the [Lovable Project](https://lovable.dev/projects/e725613f-1a63-446f-a2ba-256bc91b759f) and start prompting. |
| 13 | +### Local Development |
14 | 14 |
|
15 | | -Changes made via Lovable will be committed automatically to this repo. |
| 15 | +1. Clone the repository: |
| 16 | +```bash |
| 17 | +git clone <YOUR_GIT_URL> |
| 18 | +cd balatrobench-site |
| 19 | +``` |
16 | 20 |
|
17 | | -**Use your preferred IDE** |
| 21 | +2. Serve the files locally: |
| 22 | +```bash |
| 23 | +# Using Python (recommended) |
| 24 | +python -m http.server 8000 |
18 | 25 |
|
19 | | -If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable. |
| 26 | +# Using Node.js (if you have it) |
| 27 | +npx serve . |
20 | 28 |
|
21 | | -The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating) |
| 29 | +# Using any other static file server |
| 30 | +``` |
22 | 31 |
|
23 | | -Follow these steps: |
| 32 | +3. Open http://localhost:8000 in your browser |
24 | 33 |
|
25 | | -```sh |
26 | | -# Step 1: Clone the repository using the project's Git URL. |
27 | | -git clone <YOUR_GIT_URL> |
| 34 | +### GitHub Pages Deployment |
28 | 35 |
|
29 | | -# Step 2: Navigate to the project directory. |
30 | | -cd <YOUR_PROJECT_NAME> |
| 36 | +1. Push your changes to the `main` branch |
| 37 | +2. Go to repository Settings > Pages |
| 38 | +3. Set source to "Deploy from a branch" |
| 39 | +4. Select `main` branch and `/ (root)` folder |
| 40 | +5. Your site will be available at `https://yourusername.github.io/balatrobench-site` |
31 | 41 |
|
32 | | -# Step 3: Install the necessary dependencies. |
33 | | -npm i |
| 42 | +## 📁 Project Structure |
34 | 43 |
|
35 | | -# Step 4: Start the development server with auto-reloading and an instant preview. |
36 | | -npm run dev |
37 | 44 | ``` |
| 45 | +├── index.html # Main page (Official Benchmark) |
| 46 | +├── community.html # Community submissions page |
| 47 | +├── submit.html # Submission guidelines |
| 48 | +├── js/ |
| 49 | +│ └── app.js # JavaScript for data loading |
| 50 | +├── data/ |
| 51 | +│ ├── leaderboard.json # Official benchmark results |
| 52 | +│ └── strategies/ # Community submissions |
| 53 | +│ ├── strategy1.json |
| 54 | +│ └── strategy2.json |
| 55 | +└── README.md |
| 56 | +``` |
| 57 | + |
| 58 | +## 🏆 Official Benchmark |
| 59 | + |
| 60 | +The official leaderboard tracks performance across standardized seeds and configurations: |
| 61 | + |
| 62 | +- **Balatro Version**: v1.0.1n |
| 63 | +- **Seeds**: 100 consistent seeds for reproducibility |
| 64 | +- **Metrics**: Average ante reached, win rate, token efficiency |
| 65 | +- **Models**: GPT-4o, Claude-3.5-Sonnet, Gemini-Pro, and more |
| 66 | + |
| 67 | +## 👥 Community Contributions |
| 68 | + |
| 69 | +### Submitting Your Strategy |
| 70 | + |
| 71 | +1. **Fork this repository** |
| 72 | +2. **Create a strategy file** in `data/strategies/` following this format: |
| 73 | + |
| 74 | +```json |
| 75 | +{ |
| 76 | + "title": "Your Strategy Name", |
| 77 | + "author": "YourUsername", |
| 78 | + "model": "GPT-4o", |
| 79 | + "score": "8.5", |
| 80 | + "winRate": "75%", |
| 81 | + "avgTokens": "15000", |
| 82 | + "date": "2024-01-20", |
| 83 | + "description": "Brief description of your approach", |
| 84 | + "prompt": "Your full system prompt...", |
| 85 | + "methodology": "Detailed explanation...", |
| 86 | + "results": { |
| 87 | + "seeds": [1, 2, 3], |
| 88 | + "scores": [8.2, 8.8, 8.1] |
| 89 | + }, |
| 90 | + "tags": ["tag1", "tag2"] |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +3. **Submit a Pull Request** with title: "Community Submission: [Your Strategy Name]" |
| 95 | + |
| 96 | +### Strategy Requirements |
| 97 | + |
| 98 | +- ✅ Valid benchmark results on standard seeds |
| 99 | +- ✅ Clear strategy description and methodology |
| 100 | +- ✅ Reproducible results |
| 101 | +- ✅ Follows JSON schema format |
| 102 | +- ✅ No offensive or inappropriate content |
| 103 | + |
| 104 | +## 🛠️ Technologies Used |
| 105 | + |
| 106 | +- **HTML5** - Semantic markup |
| 107 | +- **Tailwind CSS** - Styling (via CDN) |
| 108 | +- **Vanilla JavaScript** - Dynamic content loading |
| 109 | +- **Font Awesome** - Icons (via CDN) |
| 110 | +- **JSON** - Data storage |
| 111 | + |
| 112 | +## 📊 Data Management |
| 113 | + |
| 114 | +All data is stored in JSON files for simplicity: |
| 115 | + |
| 116 | +- `data/leaderboard.json` - Official benchmark results |
| 117 | +- `data/strategies/*.json` - Community submissions |
| 118 | + |
| 119 | +This approach allows for: |
| 120 | +- Version control of all data |
| 121 | +- Easy community contributions via PRs |
| 122 | +- No database setup required |
| 123 | +- GitHub Pages compatibility |
38 | 124 |
|
39 | | -**Edit a file directly in GitHub** |
| 125 | +## 🤝 Contributing |
40 | 126 |
|
41 | | -- Navigate to the desired file(s). |
42 | | -- Click the "Edit" button (pencil icon) at the top right of the file view. |
43 | | -- Make your changes and commit the changes. |
| 127 | +We welcome contributions! You can: |
44 | 128 |
|
45 | | -**Use GitHub Codespaces** |
| 129 | +1. **Submit strategies** via pull requests |
| 130 | +2. **Report issues** or suggest improvements |
| 131 | +3. **Improve the website** (design, features, documentation) |
46 | 132 |
|
47 | | -- Navigate to the main page of your repository. |
48 | | -- Click on the "Code" button (green button) near the top right. |
49 | | -- Select the "Codespaces" tab. |
50 | | -- Click on "New codespace" to launch a new Codespace environment. |
51 | | -- Edit files directly within the Codespace and commit and push your changes once you're done. |
| 133 | +## 📈 Adding New Official Results |
52 | 134 |
|
53 | | -## What technologies are used for this project? |
| 135 | +To update the official leaderboard: |
54 | 136 |
|
55 | | -This project is built with: |
| 137 | +1. Edit `data/leaderboard.json` |
| 138 | +2. Follow the existing schema |
| 139 | +3. Submit a pull request |
56 | 140 |
|
57 | | -- Vite |
58 | | -- TypeScript |
59 | | -- React |
60 | | -- shadcn-ui |
61 | | -- Tailwind CSS |
| 141 | +## 🔧 Customization |
62 | 142 |
|
63 | | -## How can I deploy this project? |
| 143 | +Want to customize the site? |
64 | 144 |
|
65 | | -Simply open [Lovable](https://lovable.dev/projects/e725613f-1a63-446f-a2ba-256bc91b759f) and click on Share -> Publish. |
| 145 | +- **Styling**: Modify Tailwind classes in HTML files |
| 146 | +- **Functionality**: Edit `js/app.js` |
| 147 | +- **Data**: Add/modify JSON files in `data/` |
| 148 | +- **Pages**: Create new HTML files following the existing pattern |
66 | 149 |
|
67 | | -## Can I connect a custom domain to my Lovable project? |
| 150 | +## 📜 License |
68 | 151 |
|
69 | | -Yes, you can! |
| 152 | +This project is open source. Feel free to use, modify, and distribute. |
70 | 153 |
|
71 | | -To connect a domain, navigate to Project > Settings > Domains and click Connect Domain. |
| 154 | +## 🙋♀️ Support |
72 | 155 |
|
73 | | -Read more here: [Setting up a custom domain](https://docs.lovable.dev/tips-tricks/custom-domain#step-by-step-guide) |
| 156 | +- Open an issue on GitHub |
| 157 | +- Join our Discord community |
| 158 | +- Email: community@balatrobench.dev |
0 commit comments