Skip to content

Commit ee40756

Browse files
S1M0N38S1M0N38
committed
docs: add CONTRIBUTING.md
1 parent d900324 commit ee40756

1 file changed

Lines changed: 192 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Contributing to BalatroBench
2+
3+
Welcome to the BalatroBench community! We're excited to see your custom strategies and approaches to playing Balatro with AI. This guide will walk you through the process of submitting your own strategy to our community leaderboard.
4+
5+
## 🚀 Quick Submission Guide
6+
7+
Contributing to BalatroBench is simple and follows a standard GitHub workflow:
8+
9+
1. **Fork & Clone** - Fork the repository and clone it to your local machine
10+
2. **Create JSON** - Add your strategy as a JSON file in the `data/strategies/` folder
11+
3. **Submit PR** - Create a pull request with your strategy data
12+
13+
## 📋 Detailed Instructions
14+
15+
### Step 1: Fork the Repository
16+
17+
Start by forking the BalatroBench repository on GitHub, then clone it locally:
18+
19+
```bash
20+
git clone https://github.com/YOUR_USERNAME/balatrobench.git
21+
cd balatrobench
22+
```
23+
24+
### Step 2: Create Your Strategy File
25+
26+
Create a new JSON file in the `data/strategies/` folder with a descriptive filename (e.g., `your-strategy-name.json`).
27+
28+
#### Required JSON Schema
29+
30+
Your strategy file must follow this exact structure:
31+
32+
```json
33+
{
34+
"title": "Your Strategy Name",
35+
"author": "YourUsername",
36+
"model": "GPT-4o / Claude-3.5-Sonnet / etc",
37+
"score": "8.5",
38+
"winRate": "75%",
39+
"avgTokens": "15000",
40+
"date": "2024-01-20",
41+
"description": "Brief description of your strategy",
42+
"prompt": "Your full system prompt here...",
43+
"methodology": "Explanation of your approach",
44+
"results": {
45+
"seeds": [1, 2, 3, ...],
46+
"scores": [8.2, 8.8, 8.1, ...]
47+
}
48+
}
49+
```
50+
51+
#### Field Descriptions
52+
53+
- **title**: A clear, descriptive name for your strategy
54+
- **author**: Your GitHub username or preferred name
55+
- **model**: The AI model used (e.g., "GPT-4o", "Claude-3.5-Sonnet", "Gemini-Pro")
56+
- **score**: Average ante reached as a string (e.g., "8.5")
57+
- **winRate**: Percentage of games won as a string (e.g., "75%")
58+
- **avgTokens**: Average tokens used per game as a string (e.g., "15000")
59+
- **date**: Submission date in YYYY-MM-DD format
60+
- **description**: Brief summary of your strategy approach (1-2 sentences)
61+
- **prompt**: Your complete system prompt used for the AI
62+
- **methodology**: Detailed explanation of your approach, testing process, and any insights
63+
- **results**: Object containing arrays of test seeds and corresponding scores
64+
65+
### Step 3: Submit Pull Request
66+
67+
Once your strategy file is ready:
68+
69+
1. Add and commit your changes:
70+
```bash
71+
git add data/strategies/your-strategy-name.json
72+
git commit -m "Add [Your Strategy Name] community submission"
73+
git push origin main
74+
```
75+
76+
2. Create a pull request on GitHub with the title: **"Community Submission: [Your Strategy Name]"**
77+
78+
3. In the PR description, include:
79+
- Brief overview of your strategy
80+
- Any notable insights or discoveries
81+
- Confirmation that results are reproducible
82+
83+
## ✅ Submission Requirements
84+
85+
Before submitting, ensure your strategy meets these requirements:
86+
87+
- ✅ **Valid benchmark results** on standard seeds
88+
- ✅ **Clear strategy description** and detailed methodology
89+
- ✅ **JSON file follows the required schema** exactly
90+
- ✅ **Results are reproducible** by others
91+
- ✅ **No offensive or inappropriate content** in any fields
92+
- ✅ **Unique strategy name** not already used in the repository
93+
- ✅ **Complete prompt included** for transparency
94+
95+
## 📊 Testing Your Strategy
96+
97+
To ensure quality submissions, your strategy should be tested against:
98+
99+
- **Standard Seeds**: Use consistent seeds for reproducible results
100+
- **Multiple Runs**: Test across various seeds to get reliable averages
101+
- **Documentation**: Record your testing methodology and any variations
102+
103+
### Recommended Testing Process
104+
105+
1. Run your strategy on at least 10-20 different seeds
106+
2. Record the ante reached for each game
107+
3. Calculate win rate and average performance
108+
4. Document any interesting patterns or insights
109+
5. Ensure results can be reproduced by others
110+
111+
## 📥 Strategy Template
112+
113+
Use this template to get started quickly:
114+
115+
```json
116+
{
117+
"title": "Your Strategy Name",
118+
"author": "YourUsername",
119+
"model": "Model Name (e.g., GPT-4o)",
120+
"score": "0.0",
121+
"winRate": "0%",
122+
"avgTokens": "0",
123+
"date": "2024-01-20",
124+
"description": "Brief description of your strategy approach",
125+
"prompt": "Your full system prompt here...",
126+
"methodology": "Detailed explanation of your methodology",
127+
"results": {
128+
"seeds": [],
129+
"scores": [],
130+
"notes": "Any additional notes about the results"
131+
}
132+
}
133+
```
134+
135+
## 🔍 Review Process
136+
137+
All community submissions go through a review process:
138+
139+
1. **Automated checks** for JSON validity and schema compliance
140+
2. **Manual review** for content quality and appropriateness
141+
3. **Result verification** when possible
142+
4. **Feedback and iteration** if changes are needed
143+
144+
We aim to review submissions within 1-2 weeks of submission.
145+
146+
## 🏷️ Strategy Categories
147+
148+
Consider tagging your strategy with relevant approaches:
149+
150+
- **Aggressive**: High-risk, high-reward strategies
151+
- **Conservative**: Safe, consistent gameplay approaches
152+
- **Synergy-focused**: Strategies emphasizing joker combinations
153+
- **Economic**: Money and shop management focused
154+
- **Meta-exploitation**: Strategies targeting specific game mechanics
155+
- **Experimental**: Novel or unconventional approaches
156+
157+
## 🎯 Tips for Success
158+
159+
- **Be specific**: Detailed descriptions help others understand your approach
160+
- **Show your work**: Include methodology and testing process
161+
- **Be transparent**: Share your complete prompt for reproducibility
162+
- **Document insights**: Include any interesting discoveries or patterns
163+
- **Test thoroughly**: Ensure your results are consistent and reproducible
164+
165+
## 🤝 Community Guidelines
166+
167+
- Be respectful and constructive in discussions
168+
- Share knowledge and insights with others
169+
- Credit inspiration from other strategies when applicable
170+
- Focus on improving AI performance in Balatro
171+
- Help review and test other community submissions
172+
173+
## ❓ Need Help?
174+
175+
If you have questions about the submission process:
176+
177+
- **GitHub Issues**: Open an issue in the repository for technical problems
178+
- **Discussions**: Use GitHub Discussions for strategy questions and community chat
179+
- **Discord**: Join our Discord community for real-time discussions
180+
- **Email**: Reach out to community@balatrobench.dev for direct support
181+
182+
## 📜 Code of Conduct
183+
184+
By participating in BalatroBench, you agree to:
185+
186+
- Provide accurate and honest results
187+
- Respect other contributors and their work
188+
- Use appropriate and professional language
189+
- Focus discussions on strategy and performance improvement
190+
- Follow GitHub's Terms of Service and Community Guidelines
191+
192+
Thank you for contributing to BalatroBench! We look forward to seeing your innovative approaches to AI-powered Balatro gameplay.

0 commit comments

Comments
 (0)
⚡