Skip to content

Commit 234daa4

Browse files
S1M0N38S1M0N38
committed
docs: update CONTRIBUTING.md
1 parent fbb8007 commit 234daa4

1 file changed

Lines changed: 38 additions & 163 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 38 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -1,192 +1,67 @@
11
# Contributing to BalatroBench
22

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.
3+
Welcome to the BalatroBench community! We're excited to see your custom strategies for playing Balatro with AI. Contributing is simple: test your strategy locally, then submit it through our community form.
44

55
## 🚀 Quick Submission Guide
66

7-
Contributing to BalatroBench is simple and follows a standard GitHub workflow:
7+
1. **Test Locally** - Develop and test your strategy using `balatrollm`
8+
2. **Submit Form** - Fill out the embedded form on our community page
9+
3. **Server Validation** - We'll run your strategy on our servers
810

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
11+
## 📋 Step-by-Step Instructions
1212

13-
## 📋 Detailed Instructions
13+
### Step 1: Develop Your Strategy
1414

15-
### Step 1: Fork the Repository
16-
17-
Start by forking the BalatroBench repository on GitHub, then clone it locally:
15+
Create your strategy using the [`balatrollm`](https://github.com/S1M0N38/balatrollm) framework:
1816

1917
```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-
}
18+
# Test your strategy locally
19+
balatrollm --strategy path/to/strategy/directory
4920
```
5021

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
22+
Test thoroughly with different seeds and game scenarios to ensure your strategy works consistently.
6423

65-
### Step 3: Submit Pull Request
24+
### Step 2: Submit Through Community Form
6625

67-
Once your strategy file is ready:
26+
Visit the **Community** page on our website and find the submission form. You'll need to provide:
6827

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-
```
28+
**Required Fields:**
29+
- **Provider/Model**: The AI provider and model
30+
- **Base URL**: API endpoint for your chosen provider
31+
- **API Key**: Your API key for the service
32+
- **Strategy Name**: A clear, descriptive name for your strategy
33+
- **Author**: Your name or GitHub username
34+
- **STRATEGY.md.jinja**: Paste your complete strategy template directly into the form
13435

135-
## 🔍 Review Process
36+
### Step 3: Server Validation
13637

137-
All community submissions go through a review process:
38+
After submission:
39+
- We'll automatically run your strategy on our benchmark servers
40+
- Results will be added to the leaderboard if validation passes
41+
- No manual review process - fully automated
13842

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
43+
## 🎯 Strategy Development Tips
14344

144-
We aim to review submissions within 1-2 weeks of submission.
45+
- **Test Thoroughly**: Run multiple games with different seeds locally
46+
- **Clear Instructions**: Write detailed, specific prompts for the AI
47+
- **Focus on Results**: Optimize for consistent high scores and win rates
14548

146-
## 🏷️ Strategy Categories
49+
## 📊 What Makes a Good Strategy
14750

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
51+
- **Consistency**: Performs well across different game scenarios
52+
- **Clarity**: Easy to understand and implement
53+
- **Innovation**: Brings new approaches or insights
54+
- **Reproducibility**: Others can achieve similar results
16455

16556
## 🤝 Community Guidelines
16657

167-
- Be respectful and constructive in discussions
168-
- Share knowledge and insights with others
169-
- Credit inspiration from other strategies when applicable
58+
- Be respectful and constructive
59+
- Share knowledge and insights
17060
- Focus on improving AI performance in Balatro
171-
- Help review and test other community submissions
61+
- Use appropriate language in all submissions
17262

17363
## ❓ Need Help?
17464

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
65+
Ask questions on [our Discord server](https://discord.gg/TPn6FYgGPv) in the #balatrobench channel.
19166

192-
Thank you for contributing to BalatroBench! We look forward to seeing your innovative approaches to AI-powered Balatro gameplay.
67+
Thank you for contributing to BalatroBench! We look forward to seeing your innovative AI strategies.

0 commit comments

Comments
 (0)
⚡