A Minecraft Fabric mod that connects the game with ATProtocol ⛏️
1# AppView Quick Start Guide
2
3## For Server Operators
4
5This guide explains how to set up and run the Minecraft AppView to display player data from your social-sync enabled server.
6
7### What is an AppView?
8
9An AppView is a service that:
10- Indexes Minecraft data published to AT Protocol
11- Provides APIs for querying leaderboards, player stats, and achievements
12- Can be integrated with Bluesky custom feeds
13- Runs independently from your Minecraft server
14
15### Prerequisites
16
17- Minecraft server with social-sync mod installed
18- Players linking their AT Protocol identities
19- Data being synced to AT Protocol (verify with `/atproto sync`)
20- A server to host the AppView service
21
22### Setup Steps
23
24#### 1. Enable Data Syncing on Your Server
25
26Ensure players are syncing data:
27
28```bash
29# In-game, ask players to run:
30/atproto sync stats on
31/atproto sync achievements on
32/atproto sync sessions on
33```
34
35Or enable in the config screen: `Mod Menu → atproto-connect → Sync Preferences`
36
37#### 2. Deploy the AppView Service
38
39The AppView service needs to run separately from Minecraft. Here's the minimal setup:
40
41**Option A: Using Docker**
42
43```dockerfile
44FROM openjdk:17
45WORKDIR /app
46COPY AppViewService.jar .
47EXPOSE 8080
48CMD ["java", "-jar", "AppViewService.jar"]
49```
50
51**Option B: Running Directly**
52
53```bash
54java -jar appview-service.jar \
55 --port 8080 \
56 --db-host localhost \
57 --db-port 5432 \
58 --db-name appview
59```
60
61#### 3. Set Up Data Subscription
62
63The AppView needs to subscribe to updates. In production, this means:
64
651. **Subscribe to AT Protocol Firehose**: Real-time record updates
662. **Run scheduled queries**: Refresh leaderboards periodically
673. **Maintain a database**: Store indexed records
68
69Simple implementation in Kotlin:
70
71```kotlin
72class FirehoseSubscriber(val appViewService: AppViewService) {
73 suspend fun subscribe() {
74 // Connect to AT Protocol firehose
75 // Example: https://jetstream.atproto.tools/
76
77 for (event in firehose.subscribe()) {
78 if (event.commit?.collection?.startsWith("com.jollywhoppers.minecraft") == true) {
79 appViewService.indexRecord(event)
80 }
81 }
82 }
83}
84```
85
86#### 4. Test the Service
87
88Once running, test with:
89
90```bash
91# Check health
92curl http://localhost:8080/health
93
94# Query a player (replace UUID)
95curl http://localhost:8080/player/550e8400-e29b-41d4-a716-446655440000
96
97# Get leaderboard
98curl http://localhost:8080/leaderboard/minecraft.mined.oak_log
99
100# Search players
101curl "http://localhost:8080/search?q=Alice"
102```
103
104#### 5. Make Public (Optional)
105
106To integrate with Bluesky:
107
1081. Deploy to a public URL (e.g., `https://minecraft-appview.example.com`)
1092. Set up CORS for Bluesky requests
1103. Register in the AT Protocol registry
111
112```bash
113# Register AppView endpoint
114curl -X POST https://your-pds.example.com/xrpc/com.atproto.repo.createRecord \
115 -H "Authorization: Bearer YOUR_TOKEN" \
116 -H "Content-Type: application/json" \
117 -d '{
118 "repo": "your.did",
119 "collection": "app.bsky.graph.follow",
120 "record": {
121 "subject": "did:web:minecraft-appview.example.com"
122 }
123 }'
124```
125
126### Monitoring
127
128Monitor your AppView with these metrics:
129
130```bash
131# Check indexing performance
132tail -f logs/appview.log | grep "Indexed"
133
134# Monitor API response times
135curl -w "Time: %{time_total}s\n" http://localhost:8080/leaderboard/minecraft.mined.oak_log
136
137# Database size
138SELECT COUNT(*) FROM indexed_records;
139```
140
141### Configuration
142
143Create `config.yaml`:
144
145```yaml
146server:
147 port: 8080
148 host: 0.0.0.0
149
150database:
151 host: localhost
152 port: 5432
153 name: appview
154 user: appview
155 password: secure_password
156
157firehose:
158 enabled: true
159 endpoint: https://jetstream.atproto.tools
160 reconnect_interval: 30
161
162cache:
163 enabled: true
164 ttl_minutes: 60
165 max_entries: 10000
166
167logging:
168 level: INFO
169 file: logs/appview.log
170```
171
172### Common Issues
173
174**Q: No data showing up**
175- A: Ensure `/atproto sync` is enabled on players' clients
176- A: Verify Firehose subscription is receiving events
177- A: Check database is initialized and accessible
178
179**Q: Leaderboard queries are slow**
180- A: Add database indexes on statistic keys
181- A: Implement Redis caching layer
182- A: Pre-compute leaderboards on schedule
183
184**Q: Players aren't finding data**
185- A: Check player privacy settings (publicStats flag)
186- A: Verify records were published to AT Protocol
187- A: Review server logs for sync errors
188
189### Performance Tips
190
1911. **Database Indexes**
192 ```sql
193 CREATE INDEX idx_player_uuid ON indexed_records(player_uuid);
194 CREATE INDEX idx_statistic_key ON indexed_records(statistic_key);
195 CREATE INDEX idx_synced_at ON indexed_records(synced_at DESC);
196 ```
197
1982. **Caching Strategy**
199 - Cache leaderboards for 10 minutes
200 - Cache player profiles for 5 minutes
201 - Cache trending achievements for 1 hour
202
2033. **Query Optimization**
204 - Paginate results (max 100 records)
205 - Use time-based filtering (last 30 days)
206 - Pre-compute common queries
207
2084. **Resource Limits**
209 - Connection pool: 20 connections
210 - Request timeout: 30 seconds
211 - Max result size: 10 MB
212
213### Integration Examples
214
215#### Bluesky Custom Feed
216
217Embed AppView data in a Bluesky custom feed:
218
219```javascript
220// Fetch top builders from AppView
221const topBuilders = await fetch(
222 'https://minecraft-appview.example.com/leaderboard/minecraft.mined.oak_log?limit=20'
223).then(r => r.json());
224
225// Create feed posts from the data
226topBuilders.data.forEach(entry => {
227 createFeedItem({
228 author: entry.username,
229 text: `🏆 ${entry.username} is #${topBuilders.data.indexOf(entry) + 1} in block mining!`,
230 metadata: {
231 statistic: entry.statistic,
232 value: entry.value
233 }
234 });
235});
236```
237
238#### Web Dashboard
239
240Display leaderboards on a website:
241
242```html
243<div id="leaderboard"></div>
244<script>
245fetch('https://minecraft-appview.example.com/leaderboard/minecraft.mined.oak_log')
246 .then(r => r.json())
247 .then(data => {
248 const html = data.data.map((entry, i) => `
249 <tr>
250 <td>${i + 1}</td>
251 <td>${entry.username}</td>
252 <td>${entry.value}</td>
253 </tr>
254 `).join('');
255 document.getElementById('leaderboard').innerHTML = `<table>${html}</table>`;
256 });
257</script>
258```
259
260### Production Checklist
261
262- [ ] Database is backed up daily
263- [ ] Firehose subscription has reconnection logic
264- [ ] CORS is properly configured
265- [ ] Rate limiting is enabled
266- [ ] Logging is configured
267- [ ] Monitoring alerts are set up
268- [ ] SSL/HTTPS is enabled
269- [ ] Privacy policies are published
270- [ ] AppView is registered in AT Protocol registry
271- [ ] Load testing has been performed
272
273### Support
274
275- Report bugs: Check the Issues page
276- Ask questions: Start a Discussion
277- See examples: `docs/examples/AppViewExample.kt`
278- Full docs: `docs/APPVIEW.md`
279
280### Next Steps
281
2821. Deploy the AppView to your infrastructure
2832. Subscribe to AT Protocol Firehose
2843. Set up monitoring and alerts
2854. Create custom feeds for your community
2865. Share leaderboards with players!