199 lines
7.2 KiB
Markdown
199 lines
7.2 KiB
Markdown
# Random Access
|
|
|
|
[](https://www.python.org/downloads/)
|
|
[](https://fastapi.tiangolo.com/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
**The backend API that powers Hack Club's Random Access You Ship, We Ship program.**
|
|
|
|
Random Access is a Hack Club You Ship, We Ship (YSWS) program, specifically focused on high school students building games that share items between them. This API makes cross-game item sharing possible, letting players carry their earned items between different games and creating a shared gaming universe where progress transcends individual games.
|
|
|
|
**Complete your game with Random Access integration and earn a high-quality game controller!**
|
|
|
|
## For Game Developers
|
|
|
|
Whether you're building your first game or you're an experienced developer, integrating with Random Access gets you a **game controller** when you complete your project! This API makes it easy to add cross-game item sharing to your game and qualify for the YSWS reward.
|
|
|
|
## How It Works for Players
|
|
|
|
1. **Earn items** in any participating game (weapons, skins, achievements, etc.)
|
|
2. **Items are saved** to your cross-game inventory automatically
|
|
3. **Use items** in other participating games - your progress follows you
|
|
4. **Discover new games** through the shared item ecosystem
|
|
|
|
## Getting Started (Game Developers)
|
|
|
|
### 1. Use the Hosted API
|
|
|
|
No setup required! The Random Access API is hosted at **https://random-access.hackclub.com** - just start making requests.
|
|
|
|
🔗 **Live API Documentation**: https://random-access.hackclub.com/docs
|
|
|
|
### 2. Authenticate Your Game
|
|
|
|
```javascript
|
|
// Example: Getting a session token for your game
|
|
const response = await fetch('https://random-access.hackclub.com/auth/login', {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({
|
|
username: 'player123',
|
|
// ... auth details
|
|
})
|
|
});
|
|
const { token } = await response.json();
|
|
```
|
|
|
|
### 3. Give Players Items
|
|
|
|
```javascript
|
|
// Example: Player earned a "Fire Sword" in your game
|
|
await fetch('https://random-access.hackclub.com/items', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Authorization': `Bearer ${token}`,
|
|
'Content-Type': 'application/json'
|
|
},
|
|
body: JSON.stringify({
|
|
name: 'Fire Sword',
|
|
type: 'weapon',
|
|
rarity: 'epic',
|
|
game_source: 'your-game-name'
|
|
})
|
|
});
|
|
```
|
|
|
|
### 4. Let Players Use Items from Other Games
|
|
|
|
```javascript
|
|
// Example: Get all items this player has earned across all games
|
|
const items = await fetch('https://random-access.hackclub.com/items', {
|
|
headers: { 'Authorization': `Bearer ${token}` }
|
|
}).then(r => r.json());
|
|
|
|
// Now player can use their "Magic Shield" from another game!
|
|
items.forEach(item => {
|
|
if (item.type === 'shield') {
|
|
// Add to player's inventory in your game
|
|
}
|
|
});
|
|
```
|
|
|
|
## Game Integration Examples
|
|
|
|
### Unity (C#)
|
|
```csharp
|
|
// Give player an item
|
|
var item = new { name = "Lightning Bolt", type = "spell", rarity = "rare" };
|
|
var json = JsonConvert.SerializeObject(item);
|
|
var content = new StringContent(json, Encoding.UTF8, "application/json");
|
|
await httpClient.PostAsync("https://random-access.hackclub.com/items", content);
|
|
```
|
|
|
|
### Godot (GDScript)
|
|
```gdscript
|
|
# Get player's items from all games
|
|
var http_request = HTTPRequest.new()
|
|
add_child(http_request)
|
|
http_request.request("https://random-access.hackclub.com/items", headers)
|
|
```
|
|
|
|
### Web Games (JavaScript)
|
|
```javascript
|
|
// Works with any web framework - React, Vue, vanilla JS, etc.
|
|
const playerItems = await fetch('https://random-access.hackclub.com/items', {
|
|
headers: { 'Authorization': `Bearer ${token}` }
|
|
}).then(r => r.json());
|
|
```
|
|
|
|
### Python Games (pygame, etc.)
|
|
```python
|
|
import requests
|
|
# Perfect for game jams and quick prototypes
|
|
response = requests.get('https://random-access.hackclub.com/items', headers=headers)
|
|
items = response.json()
|
|
```
|
|
|
|
## What Players Experience
|
|
|
|
Each game interprets shared items in ways that fit their gameplay - weapons stay weapons, armor stays armor, but players get to carry their achievements across the entire ecosystem.
|
|
|
|
## API Overview
|
|
|
|
🔗 **Live API Docs**: https://random-access.hackclub.com/docs
|
|
|
|
- **`/auth/*`** - Player login/logout and session management
|
|
- **`/items/*`** - Create, read, update items that players earn
|
|
- **`/users/*`** - Player profiles and cross-game statistics
|
|
- **`/system/*`** - Health checks and status monitoring
|
|
|
|
The API is RESTful, returns JSON, and includes detailed examples for every endpoint.
|
|
|
|
## Built for Real Games
|
|
|
|
- **Fast**: Redis caching means your game gets instant responses
|
|
- **Reliable**: Built-in rate limiting prevents abuse and ensures fair play
|
|
- **Secure**: Player data is protected with proper authentication
|
|
- **Scalable**: Handles multiple games and thousands of players
|
|
- **Cross-Platform**: Works with web games, mobile apps, desktop games, etc.
|
|
|
|
## Contributing to the Ecosystem
|
|
|
|
Show off what you built with the Random Access program:
|
|
|
|
1. **Share Your Game**: Let the community see what you created!
|
|
2. **Help Other Developers**: Answer questions and share tips
|
|
3. **Suggest Item Types**: What kinds of items would be cool to share between games?
|
|
4. **Test the API**: Report any issues you find while building
|
|
|
|
## About the Random Access You Ship, We Ship Program
|
|
|
|
Random Access is one of Hack Club's You Ship, We Ship (YSWS) programs, specifically designed for high school students building interconnected games. **Ship a completed game that integrates with this API and earn a game controller!**
|
|
|
|
This API provides the technical foundation you need to focus on making an awesome game instead of worrying about backend infrastructure. The cross-game item sharing functionality is already built - you just need to integrate it into your game to qualify for the reward.
|
|
|
|
## Contributing to the API
|
|
|
|
Want to help improve the Random Access API itself? This section is for developers who want to contribute to the backend code:
|
|
|
|
### Local Development Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/hackclub/random-access.git
|
|
cd random-access
|
|
|
|
# Install dependencies
|
|
pip install -e .[dev]
|
|
|
|
# Set up environment
|
|
cp .env.template .env
|
|
# Edit .env with your configuration
|
|
|
|
# Run locally
|
|
random-access-server
|
|
```
|
|
|
|
Your local API will be available at http://localhost:8000
|
|
|
|
### Contributing Code
|
|
|
|
1. **Report Issues**: Found a bug? Let us know!
|
|
2. **Suggest Features**: What would make game integration easier?
|
|
3. **Submit Pull Requests**: Help make this API better for everyone
|
|
4. **Share Feedback**: Let us know how we can improve the developer experience
|
|
|
|
## Technical Details
|
|
|
|
**For developers who want to know what's under the hood:**
|
|
|
|
- Built with FastAPI (modern Python web framework)
|
|
- Redis for high-performance caching
|
|
- Airtable for data persistence
|
|
- Comprehensive security with CORS, rate limiting, and input validation
|
|
- Full async/await support for optimal performance
|
|
- OpenAPI documentation with interactive examples
|
|
|
|
---
|
|
|
|
**Ready to earn your game controller?** Check out the [API Documentation](https://random-access.hackclub.com/docs), integrate the Random Access API into your game, and ship your completed project to qualify for the YSWS reward!
|