Skip to content

Commit 460e1c9

Browse files
ThePythonGuy3ThePythonGuy3
committed
Finished README and completed CI
1 parent 99c39d1 commit 460e1c9

File tree

4 files changed

+203
-98
lines changed

4 files changed

+203
-98
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,17 +26,21 @@ jobs:
2626
- name: Build mod artifact
2727
run: |
2828
chmod +x gradlew
29-
./gradlew clean dex
29+
./gradlew clean
30+
./gradlew lib
31+
./gradlew dex
3032
- name: Upload built mod artifact as a GitHub Action artifact
3133
uses: actions/upload-artifact@v4
3234
if: github.event_name == 'push' || github.event_name == 'pull_request'
3335
with:
3436
name: CustomJsonLib (zipped)
35-
path: build/libs/CustomJsonLibCrossPlatform.jar
37+
path: |
38+
build/libs/CustomJsonLibCrossPlatform.jar
39+
build/libs/CustomJsonLib.jar
3640
if-no-files-found: error
3741
compression-level: 0
3842
- name: Upload built mod artifact into release
3943
uses: softprops/action-gh-release@v2
4044
if: github.event_name == 'release' && github.event.action == 'created'
4145
with:
42-
files: build/libs/CustomJsonLibCrossPlatform.jar
46+
files: ${{ endsWith(github.event.release.name, 'Library') && 'build/libs/CustomJsonLib.jar' || 'build/libs/CustomJsonLibCrossPlatform.jar' }}

‎README.md‎

Lines changed: 193 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,42 @@
1-
# Custom JSON Lib for Mindustry
1+
# <img src="icon.png" alt="Mod Icon" width="32" height="32"/> Custom JSON Lib for Mindustry
22

33
Allows [Mindustry](https://github.com/Anuken/Mindustry) Mods to add and read custom JSON tags to act as libraries for other Mindustry Mods.
44

5+
> [!NOTE]
6+
> If your mod uses `CustomJsonLib`, `CustomJsonLib` will need to be installed in Mindustry as a mod, either through the Mod Browser or manually. Otherwise, all the functionality implemented herein will not be available.
7+
58
## How do I use this library?
69

710
<details>
811
<summary>I want to implement new JSON tags</summary>
9-
10-
## My mod is written in Java
11-
If your mod is written in Java (and is, hence, a Jar mod), use this method.
12-
13-
1. **Add the library as a dependency in your** `mod.[h]json` **file:**
14-
15-
> You can SKIP this step if your mod supports this library but does not *require* it to function.
16-
17-
&nbsp;&nbsp;&nbsp;JSON:
12+
13+
## My mod is written in Java
14+
If your mod is written in Java (and is, hence, a Jar mod), use this method.
15+
16+
1. **Add the library as a dependency in your** `mod.[h]json` **file:**
17+
18+
> You can SKIP this step if your mod supports this library but does not *require* it to function.
19+
20+
&nbsp;&nbsp;&nbsp;JSON:
1821
```json
1922
"dependencies": [
20-
"pyguy.jsonlib"
21-
]
23+
"pyguy.jsonlib"
24+
]
2225
```
23-
&nbsp;&nbsp;&nbsp;HJSON:
26+
&nbsp;&nbsp;&nbsp;HJSON:
2427
```
2528
dependencies: [
2629
pyguy.jsonlib
2730
]
2831
```
29-
30-
2. **Add the library Jar file into your project as a Java dependency:**
31-
32-
This is a necessary step before you can compile your mod, since the library Jar contains the methods (functions) used to access custom JSON tags.\
33-
To get the library file, either download the latest release of `CustomJsonLib.jar` (NOT `CustomJsonLibDesktop.jar`) from Releases, or compile your own (See [Building](#building) below).
34-
35-
36-
Copy the file into a directory called `lib/` you must create on your mod's root directory:
32+
33+
2. **Add the library Jar file into your project as a Java dependency:**
34+
35+
This is a necessary step before you can compile your mod, since the library Jar contains the methods (functions) used to access custom JSON tags.\
36+
To get the library file, either download the latest release of `CustomJsonLib.jar` (NOT `CustomJsonLibDesktop.jar`) from Releases, or compile your own (See [Building](#building) below).
37+
38+
39+
Copy the file into a directory called `lib/` you must create on your mod's root directory:
3740
```
3841
- YourAwesomeMod/
3942
- src/
@@ -42,69 +45,69 @@ Allows [Mindustry](https://github.com/Anuken/Mindustry) Mods to add and read cus
4245
- lib/
4346
- CustomJsonLib.jar
4447
```
45-
46-
Assuming you're using Gradle as your build system, add the Jar file as a dependency in your mod's `build.gradle.kts`:
48+
49+
Assuming you're using Gradle as your build system, add the Jar file as a dependency in your mod's `build.gradle.kts`:
4750
```kotlin
4851
project(":"){
52+
// ...
53+
54+
dependencies{
4955
// ...
50-
51-
dependencies{
52-
// ...
53-
compileOnly(files(layout.projectDirectory.dir("lib").file("CustomJsonLib.jar")))
54-
}
55-
56-
// ...
56+
compileOnly(files(layout.projectDirectory.dir("lib").file("CustomJsonLib.jar")))
5757
}
58+
59+
// ...
60+
}
5861
```
59-
If you are using other build systems, ensure that you are adding the library as a Compile Only dependency. This is VERY important and your mod will not work properly otherwise.
60-
61-
62-
Do note that most IDEs will not immediately detect the library after this step. Please restart your IDE or reload the Gradle script (ask your favorite Search Engine how to do this) for it to take effect.
63-
64-
3. **Use the library**
65-
66-
Now the library is part of your project. This does NOT mean it will be shipped with your Jar files, and it makes the files no larger, it just allows for compilation and usage of the library methods.
67-
68-
69-
The content table for JSON tags is created and ready to be used from your mod's `init()` method onward. If you plan on checking all content for custom JSON tags, it is recommended to do so after the client loads, like so:
62+
If you are using other build systems, ensure that you are adding the library as a Compile Only dependency. This is VERY important and your mod will not work properly otherwise.
63+
64+
65+
Do note that most IDEs will not immediately detect the library after this step. Please restart your IDE or reload the Gradle script (ask your favorite Search Engine how to do this) for it to take effect.
66+
67+
3. **Use the library**
68+
69+
Now the library is part of your project. This does NOT mean it will be shipped with your Jar files, and it makes the files no larger, it just allows for compilation and usage of the library methods.
70+
71+
72+
The content table for JSON tags is created and ready to be used from your mod's `init()` method onward. If you plan on checking all content for custom JSON tags, it is recommended to do so after the client loads, like so:
7073
```java
7174
@Override
72-
public void init()
73-
{
74-
Events.on(EventType.ClientLoadEvent.class, event -> {
75-
// Your code here
76-
});
77-
}
75+
public void init()
76+
{
77+
Events.on(EventType.ClientLoadEvent.class, event -> {
78+
// Your code here
79+
});
80+
}
7881
```
79-
80-
To know what methods this library supports, see [Using the Library](#using-the-library) below.
81-
82+
83+
To know what methods this library supports, see [Using the Library](#using-the-library) below.
84+
8285
<br/>
83-
84-
## My mod is written in JavaScript and [H]JSON
85-
If your mod is written in JavaScript and [H]JSON (and is, hence, a standard Mindustry mod), use this method.
86-
87-
1. **Add the library as a dependency in your** `mod.[h]json` **file:**
88-
89-
> You can SKIP this step if your mod supports this library but does not *require* it to function.
90-
91-
&nbsp;&nbsp;&nbsp;JSON:
86+
87+
## My mod is written in JavaScript and [H]JSON
88+
If your mod is written in JavaScript and [H]JSON (and is, hence, a standard Mindustry mod), use this method.
89+
90+
1. **Add the library as a dependency in your** `mod.[h]json` **file:**
91+
92+
> You can SKIP this step if your mod supports this library but does not *require* it to function.
93+
94+
&nbsp;&nbsp;&nbsp;JSON:
9295
```json
9396
"dependencies": [
94-
"pyguy.jsonlib"
95-
]
97+
"pyguy.jsonlib"
98+
]
9699
```
97-
&nbsp;&nbsp;&nbsp;HJSON:
100+
&nbsp;&nbsp;&nbsp;HJSON:
98101
```
99102
dependencies: [
100103
pyguy.jsonlib
101104
]
102105
```
103-
104-
2. **Create a reference to JsonLibWrapper for your mod:**
105-
106-
Modded classpaths are not included into Rhino JS by default (this means that you cannot directly access the library from JS, you need some work for it).\
107-
For this very reason, you need to create a reference that you can use within your mod. To do this, append this to the end of your `main.js` script:
106+
107+
2. **Create a reference to JsonLibWrapper for your mod:**
108+
109+
Modded classpaths are not included into Rhino JS by default (this means that you cannot directly access the library from JS, you need some work for it).\
110+
For this very reason, you need to create a reference that you can use within your mod. To do this, append this to the end of your `main.js` script:
108111
```javascript
109112
var JsonLibWrapper = null;
110113
Events.on(ClientLoadEvent, event => {
@@ -121,44 +124,44 @@ Allows [Mindustry](https://github.com/Anuken/Mindustry) Mods to add and read cus
121124
}
122125
});
123126
```
124-
125-
After this is executed, JsonLibWrapper will have one of two values: `null` if the CustomJsonLib is not currently installed in Mindustry, or the API object that you can use to work with the library otherwise.
126-
Do note that only AFTER the client has loaded will JsonLibWrapper have a value, and if CustomJsonLib is not installed in Mindustry, it will not throw an error but rather it will not execute your code at all.
127-
128-
3. **Use the library**
129-
130-
Now the library is part of your project.\
131-
To know what methods this library supports, see [Using the Library](#using-the-library) below
127+
128+
After this is executed, JsonLibWrapper will have one of two values: `null` if the CustomJsonLib is not currently installed in Mindustry, or the API object that you can use to work with the library otherwise.
129+
Do note that only AFTER the client has loaded will JsonLibWrapper have a value, and if CustomJsonLib is not installed in Mindustry, it will not throw an error but rather it will not execute your code at all.
130+
131+
3. **Use the library**
132+
133+
Now the library is part of your project.\
134+
To know what methods this library supports, see [Using the Library](#using-the-library) below
132135
</details>
133136

134137
<br/>
135138

136139
<details>
137140
<summary>I want to use JSON tags implemented by other Mods</summary>
138-
141+
139142
<br/>
140-
141-
To add custom tags implemented by other Mods, follow this structure:
142143

143-
144-
Let's say you want to add to a block named `weigthedBomb` a tag called `weight` from a mod whose internal name is `physics-mod`, and a tag called `explosionSize` from a mod whose internal name is `super-explosions`.
144+
To add custom tags implemented by other Mods, follow this structure:
145145

146-
In your content's [h]json file you'd add the following:
147-
148-
&nbsp;&nbsp;&nbsp;JSON (weightedBomb.json):
146+
147+
Let's say you want to add to a block named `weigthedBomb` a tag called `weight` from a mod whose internal name is `physics-mod`, and a tag called `explosionSize` from a mod whose internal name is `super-explosions`.
148+
149+
In your content's [h]json file you'd add the following:
150+
151+
&nbsp;&nbsp;&nbsp;JSON (weightedBomb.json):
149152
```json
150153
{
151-
"type": "Block",
154+
"type": "Block",
152155

153-
...
156+
...
154157

155-
"customJson": [
156-
"physics-mod-weight": 45,
157-
"super-explosions-explosionSize": "huge"
158-
]
159-
}
158+
"customJson": [
159+
"physics-mod-weight": 45,
160+
"super-explosions-explosionSize": "huge"
161+
]
162+
}
160163
```
161-
&nbsp;&nbsp;&nbsp;HJSON (weightedBomb.hjson):
164+
&nbsp;&nbsp;&nbsp;HJSON (weightedBomb.hjson):
162165
```
163166
type: Block
164167
@@ -170,7 +173,7 @@ Allows [Mindustry](https://github.com/Anuken/Mindustry) Mods to add and read cus
170173
]
171174
```
172175

173-
> IMPORTANT: `type` here is added for illustration purposes only. The only part that matters is the `customJson` array.
176+
> IMPORTANT: `type` here is added for illustration purposes only. The only part that matters is the `customJson` array.
174177
175178
</details>
176179

@@ -199,6 +202,104 @@ If you want to support these in your own Mods, these are the tags implemented:
199202
- `physics-mod-objectType`: Indicates the type of physicsObject your Block is. Options: [`sphere`, `staticMesh`, `breakableObject`] (string)
200203
```
201204

205+
## Using the Library
206+
207+
If your mod is using Java, you're gonna have to import the CustomJsonLib package:
208+
209+
```java
210+
import pyguy.jsonlib.JsonLibWrapper;
211+
```
212+
213+
### What methods does this library implement (Java and JS):
214+
215+
Read a String custom tag named `fieldName` from a piece of content with the name `internalContentName`.
216+
```java
217+
String JsonLibWrapper.GetStringField(String internalContentName, String fieldName);
218+
```
219+
220+
221+
Read a Long (natural number) custom tag named `fieldName` from a piece of content with the name `internalContentName`.
222+
```java
223+
Long JsonLibWrapper.GetLongField(String internalContentName, String fieldName);
224+
```
225+
226+
227+
Read a Double (real number) custom tag named `fieldName` from a piece of content with the name `internalContentName`.
228+
```java
229+
Double JsonLibWrapper.GetDoubleField(String internalContentName, String fieldName);
230+
```
231+
232+
233+
Read a Boolean custom tag named `fieldName` from a piece of content with the name `internalContentName`.
234+
```java
235+
Boolean JsonLibWrapper.GetBooleanField(String internalContentName, String fieldName);
236+
```
237+
238+
Read a raw custom tag named `fieldName` from a piece of content with the name `internalContentName`. This should be used to read objects and arrays.
239+
This method returns a [JsonValue](https://github.com/Anuken/Arc/blob/master/arc-core/src/arc/util/serialization/JsonValue.java).
240+
```java
241+
JsonValue JsonLibWrapper.GetBooleanField(String internalContentName, String fieldName);
242+
```
243+
244+
<details>
245+
<summary>Example code snippet for Java</summary>
246+
247+
<br/>
248+
249+
```java
250+
@Override
251+
public void init()
252+
{
253+
Events.on(EventType.ClientLoadEvent.class, event -> {
254+
if (Vars.mods.getMod("pyguy.jsonlib") != null)
255+
{
256+
Vars.content.getBy(ContentType.block).each(blockContent -> {
257+
if (blockContent instanceof Block block)
258+
{
259+
Boolean replaceLocalized = JsonLibWrapper.GetBooleanField(block.name, "example-mod-replaceLocalized");
260+
261+
if (replaceLocalized != null && replaceLocalized)
262+
{
263+
block.localizedName = "Replaced";
264+
}
265+
}
266+
});
267+
}
268+
});
269+
}
270+
```
271+
</details>
272+
273+
<details>
274+
<summary>Example code snippet for JavaScript</summary>
275+
276+
<br/>
277+
278+
```javascript
279+
var JsonLibWrapper = null;
280+
Events.on(ClientLoadEvent, event => {
281+
let jsonLibMod = Vars.mods.getMod("pyguy.jsonlib");
282+
283+
if (jsonLibMod)
284+
{
285+
if (jsonLibMod.enabled()) JsonLibWrapper = jsonLibMod.loader.loadClass("pyguy.jsonlib.JsonLibWrapper").newInstance();
286+
}
287+
288+
if (JsonLibWrapper)
289+
{
290+
Vars.content.getBy(ContentType.block).each(blockContent => {
291+
let replaceLocalized = JsonLibWrapper.GetBooleanField(block.name, "example-mod-replaceLocalized");
292+
293+
if (replaceLocalized)
294+
{
295+
block.localizedName = "Replaced";
296+
}
297+
}
298+
}
299+
});
300+
```
301+
</details>
302+
202303
## Building
203304
204305
This mod is, in theory, cross-platform, but only Windows has been tested. The only platform not supported is iOS, just because it does not allow for Jar mods to be installed.

‎mod.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"displayName": "Custom Json Lib",
3-
"description": "Allows Java mods to create and read custom json fields from other mods.",
3+
"description": "Allows mods to create and read custom json tags from other mods, acting as libraries for JSON/JS mods.",
44
"version": "v1.0",
55
"minGameVersion": "146",
66
"author": "PyGuy (ThePythonGuy3)",

0 commit comments

Comments
 (0)