Skip to content

Commit 1e5374b

Browse files
DecDuckDecDuck
committed
feat: add initial library documentation
1 parent dde5307 commit 1e5374b

File tree

5 files changed

+198
-6
lines changed

5 files changed

+198
-6
lines changed

‎src/app/web/library/page.mdx

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
export const metadata = {
2+
title: 'Library',
3+
description:
4+
"On this page, we'll dive into how to manage the instance's library and sources.",
5+
}
6+
7+
# Library
8+
9+
Drop supports having more than one library 'source' enabled at a time. This allows users to use multiple folders on their server, and merge all the separate libraries into one.
10+
11+
Each library source has a specific type, which defines how it connects to games:
12+
13+
- Drop-style (internally `Filesystem`). The default and recommended type, it supports the versioned folders that Drop was built for.
14+
- Compatibility (internally `FlatFilesystem`). Implemented for compatibility with GameVault and similar libraries, doesn't use versioned folders.
15+
16+
You can read more about the user's side of things on the docs: [Library Sources](https://docs.droposs.org/docs/library).
17+
18+
<Note>
19+
We plan to add network-based library sources in the future, so keep this in
20+
mind when using the endpoints. They may take longer to return values in the
21+
future.
22+
</Note>
23+
24+
---
25+
26+
## The game model
27+
28+
The game model stores most of the metadata attached to the game, and is used to render store pages and display in clients.
29+
30+
### Properties
31+
32+
<Properties>
33+
#### Internal IDs and metadata
34+
<Property name="id" type="string">
35+
UUID of the game. Used internally to refer to this game.
36+
</Property>
37+
<Property name="metadataSource" type="string">
38+
ID of the metadata sourced originally used to import this game.
39+
</Property>
40+
<Property name="metadataId" type="string">
41+
Internal metadata source's ID for the original import.
42+
</Property>
43+
<Property name="created" type="timestamp">
44+
Timestamp of when this game was originally created.
45+
</Property>
46+
<Property name="libraryId" type="string">
47+
ID of library source this game is linked to.
48+
</Property>
49+
<Property name="libraryPath" type="string">
50+
Path within the library source this game is linked to.
51+
</Property>
52+
53+
#### Admin-provided metadata
54+
55+
<Property name="mName" type="string">
56+
The name of this game.
57+
</Property>
58+
<Property name="mShortDescription" type="string">
59+
A short description of this game, without requiring formatting.
60+
</Property>
61+
<Property name="mDescription" type="markdown">
62+
A markdown representation of the long-form description of this game.
63+
</Property>
64+
<Property name="mReleased" type="timestamp">
65+
When this game was released.
66+
</Property>
67+
68+
<Property name="mIconObjectId" type="string">
69+
Object ID of icon.
70+
</Property>
71+
<Property name="mBannerObjectId" type="string">
72+
Object ID of background banner. Usually a wide, high-resolution image.
73+
</Property>
74+
<Property name="mCoverObjectId" type="string">
75+
Object ID of cover. Usually a tall image with the title of the game.
76+
</Property>
77+
<Property name="mImageCarouselObjectIds" type="string[]">
78+
Array of object IDs shown on the store's carousel.
79+
</Property>
80+
<Property name="mImageLibraryObjectIds" type="string[]">
81+
An array of all object IDs linked to this game.
82+
</Property>
83+
84+
#### Metadata flags
85+
86+
<Property name="featured" type="boolean">
87+
Whether or not this game is featured for the carousel.
88+
</Property>
89+
</Properties>
90+
91+
---
92+
93+
## Fetch library {{ tag: 'GET', label: '/api/v1/admin/library', apilevel: "system", acl: "library:read" }}
94+
95+
<Row>
96+
<Col>
97+
98+
This endpoint fetches all unimported and imported games.
99+
100+
### Response values
101+
<Properties>
102+
103+
<Property name="unimportedGames" type="object">
104+
An object of library ID to paths that are yet to be imported.
105+
</Property>
106+
<Property name="games" type="array">
107+
An array of game objects with attached status.
108+
109+
<Properties>
110+
111+
<Property name="game" type="object">
112+
A metadata game object. Refer to [the game model](#the-game-model).
113+
</Property>
114+
<Property name="status" type="string | object">
115+
A field indicating the status of this game.
116+
117+
If it is a string, it'll be "offline", which means that the library source this game is connected to isn't working right now.
118+
119+
If it's an object, it'll look like:
120+
121+
```json
122+
{
123+
"noVersions": false,
124+
"unimportedVersions": []
125+
}
126+
```
127+
128+
</Property>
129+
</Properties>
130+
</Property>
131+
</Properties>
132+
133+
</Col>
134+
<Col sticky>
135+
136+
<CodeGroup title="Request" tag="GET" label="/api/v1/admin/library">
137+
138+
```bash {{ title: 'cURL' }}
139+
curl -G http://localhost:3000/api/v1/admin/library \
140+
-H "Authorization: Bearer {token}"
141+
```
142+
143+
```js
144+
const response = await fetch("http://localhost:3000/api/v1/admin/library", {
145+
headers: {
146+
Authorization: "Bearer {token}"
147+
},
148+
});
149+
150+
const results = await response.json();
151+
152+
```
153+
154+
</CodeGroup>
155+
156+
```json {{ title: 'Response' }}
157+
{
158+
"unimportedGames": {
159+
"myLibraryId": [ // These are paths on disk
160+
"My Game",
161+
"My Other Game",
162+
"Horizon Zero Dawn"
163+
],
164+
"myOtherLibraryId": []
165+
},
166+
"games": [
167+
{
168+
"game": { ... },
169+
"status": {
170+
"noVersions": false,
171+
"unimportedVersions": []
172+
}
173+
},
174+
{
175+
"game": { ... },
176+
"status": "offline"
177+
}
178+
]
179+
}
180+
```
181+
182+
</Col>
183+
</Row>
184+
185+
---

‎src/components/Code.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ const languageNames: Record<string, string> = {
2424
python: 'Python',
2525
ruby: 'Ruby',
2626
go: 'Go',
27-
}
27+
};
2828

2929
function getPanelTitle({
3030
title,

‎src/components/Navigation.tsx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,6 +271,7 @@ export const navigation: Array<NavGroup> = [
271271
{ title: 'Objects', href: '/web/objects' },
272272
{ title: 'Tasks', href: '/web/tasks' },
273273
{ title: 'Import', href: '/web/import' },
274+
{ title: 'Library', href: '/web/library' },
274275
],
275276
},
276277
]

‎src/components/mdx.tsx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -127,5 +127,5 @@ export function Property({
127127
)
128128
}
129129

130-
import PG from './PayloadGenerator';
131-
export const PayloadGenerator = PG;
130+
import PG from './PayloadGenerator'
131+
export const PayloadGenerator = PG

‎typography.ts

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,7 @@ export default {
2727
'--tw-prose-invert-headings': theme('colors.white'),
2828
'--tw-prose-invert-links': theme('colors.blue.400'),
2929
'--tw-prose-invert-links-hover': theme('colors.blue.500'),
30-
'--tw-prose-invert-links-underline': theme(
31-
'colors.blue.500 / 0.3',
32-
),
30+
'--tw-prose-invert-links-underline': theme('colors.blue.500 / 0.3'),
3331
'--tw-prose-invert-bold': theme('colors.white'),
3432
'--tw-prose-invert-counters': theme('colors.zinc.400'),
3533
'--tw-prose-invert-bullets': theme('colors.zinc.600'),
@@ -195,6 +193,14 @@ export default {
195193
marginTop: theme('spacing.10'),
196194
marginBottom: theme('spacing.2'),
197195
},
196+
h4: {
197+
color: 'var(--tw-prose-headings)',
198+
fontSize: theme('fontSize.sm')[0],
199+
...theme('fontSize.base')[1],
200+
fontWeight: '500',
201+
marginTop: theme('spacing.4'),
202+
marginBottom: theme('spacing.2'),
203+
},
198204

199205
// Media
200206
'img, video, figure': {

0 commit comments

Comments
 (0)