# Random Access

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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!