Skip to content

Commit e0fa4ba

Browse files
ci010ci010
committed
docs: update readme and update monitor doc
1 parent f4df375 commit e0fa4ba

File tree

3 files changed

+144
-11
lines changed

3 files changed

+144
-11
lines changed

‎README.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,6 @@ Go [Getting Started](/USAGE.md) page.
9292
| @xmcl/client | Ping Minecraft Server | [![npm version](https://img.shields.io/npm/v/@xmcl/client.svg)](https://www.npmjs.com/package/@xmcl/client) | [packages/client ](/packages/client) | Node |
9393
| @xmcl/model | Display player/block model | [![npm version](https://img.shields.io/npm/v/@xmcl/model.svg)](https://www.npmjs.com/package/@xmcl/model) | [packages/model ](/packages/model) | Browser |
9494
| @xmcl/gamesetting | Parse game setting | [![npm version](https://img.shields.io/npm/v/@xmcl/gamesetting.svg)](https://www.npmjs.com/package/@xmcl/gamesetting) | [packages/gamesetting ](/packages/gamesetting) | Node/Browser |
95-
| @xmcl/java-installer | Install Java from Mojang | [![npm version](https://img.shields.io/npm/v/@xmcl/java-installer.svg)](https://www.npmjs.com/package/@xmcl/java-installer) | [packages/java-installer ](/packages/java-installer) | Node |
9695
| @xmcl/nbt | Parse NBT | [![npm version](https://img.shields.io/npm/v/@xmcl/nbt.svg)](https://www.npmjs.com/package/@xmcl/nbt) | [packages/nbt ](/packages/nbt) | Node/Browser |
9796
| @xmcl/text-component | Parse and render Minecraft Text | [![npm version](https://img.shields.io/npm/v/@xmcl/text-component.svg)](https://www.npmjs.com/package/@xmcl/text-component ) | [packages/text-component ](/packages/text-component) | Node/Browser |
9897
| @xmcl/resource-manager | Load model from resource pack | [![npm version](https://img.shields.io/npm/v/@xmcl/resource-manager.svg)](https://www.npmjs.com/package/@xmcl/resource-manager ) | [packages/resource-manager ](/packages/resource-manager) | Node/Browser |
@@ -109,7 +108,7 @@ See [Contribute.md](/CONTRIBUTE.md)
109108

110109
## Credit
111110

112-
[Yu Xuanchi](https://github.com/yuxuanchiadm), co-worker, quality control of this project.
111+
[Yu Xuanchi](https://github.com/yuxuanchiadm), provide some idea about NBT module.
113112

114113
[Haowei Wen](https://github.com/yushijinhun), the author of [JMCCC](https://github.com/to2mbn/JMCCC), [Authlib Injector](https://github.com/to2mbn/authlib-injector), and [Indexyz](https://github.com/Indexyz), help me a lot on Minecraft launching, authing.
115114

‎packages/client/README.md

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,16 @@ Provide some functions to query Minecraft server status.
1515
Read sever info (server ip, port) and fetch its status (ping, server motd):
1616

1717
```ts
18-
import { fetchStatus, Status } from '@xmcl/client'
19-
// or you want the raw json
20-
const rawStatusJson: Status = await fetchStatus(info);
18+
import { queryStatus, Status, QueryOptions } from '@xmcl/client'
19+
const serverInfo = {
20+
host: 'your host',
21+
port: 25565, // be default
22+
};
23+
const options: QueryOptions = {
24+
/**
25+
* see http://wiki.vg/Protocol_version_numbers
26+
*/
27+
protocol: 203,
28+
};
29+
const rawStatusJson: Status = await fetchStatus(info, options);
2130
```

‎packages/installer/README.md

Lines changed: 131 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,124 @@ Get the report of the version. It can check if version missing assets/libraries.
7979
const minecraftLocation: string;
8080
const minecraftVersionId: string;
8181

82-
const report: Diagnosis.Report = await Diagnosis.diagnose(minecraftLocation, minecraftVersionId);
82+
const report: Diagnosis.MinecraftIssueReport = await Diagnosis.diagnose(minecraftLocation, minecraftVersionId);
83+
84+
const issues: Diagnosis.MinecraftIssues[] = report.issues;
85+
86+
for (let issue of issues) {
87+
switch (issue.role) {
88+
case "minecraftJar": // your jar has problem
89+
case "versionJson": // your json has problem
90+
case "library": // your lib might be missing or corrupted
91+
case "assets": // some assets are missing or corrupted
92+
// and so on
93+
}
94+
}
95+
```
96+
97+
### Progress Moniting on Installation
98+
99+
Most install function has a corresponding task function. For example, `install` function has the function name `installTask` which is the task version monitor the progress of install.
100+
101+
Here is the example of just moniting the install task overall progress:
102+
103+
```ts
104+
105+
let task: Task<ResolvedVersion> = installTask('client', versionMetadata, mcLocation);
106+
let taskHandle: TaskHandle<ResolvedVersion> = task.execute();
107+
108+
let rootTask: Task.State;
109+
taskHandle.on('execute', (task, parentTask) => {
110+
if (parentTask) {
111+
// remember which is the root tas
112+
rootTask = task;
113+
} else {
114+
// other child task executed
115+
}
116+
});
117+
taskHandle.on('update', ({ progress, total, message }, taskState) => {
118+
if (rootTask === taskState) {
119+
// root task update
120+
// you should update your ui progress
121+
} else {
122+
// other task update
123+
}
124+
});
125+
126+
// wait task finish
127+
await taskHandle.wait();
128+
129+
```
130+
131+
The task is designed to organize the all the works in a tree like structure.
132+
133+
The `installTask` has such parent/child structure
134+
135+
- install
136+
- installVersion
137+
- json
138+
- jar
139+
- installDependencies
140+
- installAssets
141+
- assetsJson
142+
- asset
143+
- installLibraries
144+
- library
145+
146+
To generally display this tree in UI. You can identify the task by its `path`.
147+
148+
```ts
149+
function updateTaskUI(task: Task.State, progress: number, total?: number) {
150+
// you can use task.path as identifier
151+
// and update the task on UI
152+
}
153+
154+
// taskHandle is the installTask handle
155+
taskHandle.on('update', ({ progress, total, message }, taskState) => {
156+
let path = taskState.path;
157+
// the path is concated from each tasks' name
158+
// it can be "install", "install.installVersion", "install.installVersion.jar"
159+
// "install.installDependencies.installAssets.assetsJson" or so on...
160+
updateTaskUI(taskState, progress, total);
161+
});
162+
```
163+
164+
If you think that's not good enough, you can assign the id to the task state by yourself.
165+
166+
In this simple case, you will enconter type error in typescript!
167+
168+
```ts
169+
taskHandle.on('execute', (task, parentTask) => {
170+
task.id = 'your-generated-id'; // type error
171+
});
172+
taskHandle.on('update', ({ progress, total, message }, taskState) => {
173+
updateTaskUI(taskState, progress, total);
174+
});
175+
function updateTaskUI(task: Task.State, progress: number, total?: number) {
176+
// update the task by task.id
177+
}
178+
```
179+
180+
You can override the type by yourself, or you can use task state factory:
181+
182+
```ts
183+
interface TaskState extends Task.State {
184+
id: string;
185+
}
186+
const factory: Task.StateFactory<TaskState> = n => ({
187+
...n,
188+
id: generateIdByYourselft(),
189+
});
190+
191+
const runtime: TaskRuntime<TaskState> = Task.createRuntime(factory);
192+
const task: Task<ResolvedVersion> = installTask('client', versionMetadata, mcLocation);
193+
194+
runtime.submit(task); // use runtime submit!
195+
196+
// listen the task event from runtime!
197+
runtime.on('update', ({progress, total}, state) => {
198+
task.id; // this will not have type error!
199+
});
83200
```
84201

85202
### Install Library/Assets with Customized Host
@@ -103,8 +220,11 @@ For example, if you want to download the library `commons-io:commons-io:2.5` fro
103220
}
104221
// return undefined if you don't want to change lib url
105222
return undefined;
106-
}
223+
},
224+
mavenHost: ['https://www.your-other-maven.org'], // you still can use this to add other maven
107225
});
226+
227+
// it will first try you libraryHost url and then try mavenHost url.
108228
```
109229

110230
To swap the assets host, you can just assign the assets host url to the options
@@ -130,6 +250,14 @@ Get the forge version info and install forge from it.
130250
await ForgeInstaller.install(firstVersionOnPage, minecraftLocation);
131251
```
132252

253+
If you know forge version and minecraft version. You can directly do such:
254+
255+
```ts
256+
import { ForgeInstaller } from "@xmcl/installer";
257+
const forgeVersion = 'a-forge-version'; // like 31.1.27
258+
await ForgeInstaller.install({ version: forgeVersion, mcversion: '1.15.2' }, minecraftLocation);
259+
```
260+
133261
Notice that this installation doesn't ensure full libraries installation.
134262
Please run `Installer.installDependencies` afther that.
135263

@@ -181,10 +309,7 @@ The module have three stage for installing new forge *(mcversion >= 1.13)*
181309

182310
The `ForgeInstaller.install` will do all of them.
183311

184-
The `ForgeInstaller.installByInstallerPartial` will do 2 and 3.
185-
186-
If you want to just do step 3, you can use `ForgeInstaller.diagnose` and find which libraries is break and use `ForgeInstaller.postProcess` to handle it.
187-
312+
The `Installer.installByProfile` will do 2 and 3.
188313

189314
### Install Java 8 From Mojang Source
190315

0 commit comments

Comments
 (0)