From 93c60fa1718e308ecd2e6093d6d3a81149555270 Mon Sep 17 00:00:00 2001 From: Deficuet <36525579+Deficuet@users.noreply.github.com> Date: Fri, 23 Dec 2022 21:31:26 -0700 Subject: [PATCH] Update README.md --- README.md | 70 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 39 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 15faa476..225e1d92 100644 --- a/README.md +++ b/README.md @@ -19,29 +19,29 @@ All the C++ code used to decode texture compression comes from [AssetStudio/Text - ByteArray, bytes of a asset bundle file. - A `String` is required as the identifier "file name" of this `ByteArray`. - Loading Configurations - - When loading file(s)/folder/ByteArray, there is a lambda parameter that can be used to configure loading behaviour. + - When loading file(s)/folder/ByteArray, there is a lambda parameter that can be used to configure loading behaviors. - The lambda will be applied **before** loading. - `offsetMode` - `MANUAL` or `AUTO` - - If the `offsetMode` is `AUTO`, all the `\x00` bytes at the beginning of the file will be ignored. The reading of the file will start at first byte that is non-zero. - - If the `offsetMode` is `MANUAL`, the number of bytes that is ignored depends on `manualIgnoredOffset`. - - `manualIgnoredOffset` + - If the `offsetMode` is `AUTO`, all the `\x00` bytes at the beginning of the file will be ignored. The reading of the file will start at the first non-zero byte. + - If the `offsetMode` is `MANUAL`, the number of bytes that is ignored depends on `manualOffset`. + - `manualOffset` - Determine the number of bytes that needs to be ignored at the beginning of the file, no matter the byte is `\x00` or not. - This propery works under `OffsetMode.MANUAL` mode only, will be ignored under `AUTO` mode. - - e.g. If an asset bundle file has 1024 bytes of useless non-zero data at the beginning, The `offsetMode` can be set to `MANUAL` and `manualIgnoredOffset` can be set to 1024 in order to skip 1024 bytes. + - e.g. If an asset bundle file has 1024 bytes of useless non-zero data at the beginning, The `offsetMode` can be set to `MANUAL` and `manualOffset` can be set to 1024 in order to skip first 1024 bytes. - Object Loading - The data of Object will not be read until you access any of its properties. - However, an access to the properties related to the Object's info will not cause the initialization of the Object. - e.g. Its `assetFile` which is a `SerializedFile`, `mPathID`, `unityVersion`, etc. Those are the properties without a `getter`. See [Object class](https://github.com/Deficuet/UnityKt/blob/main/src/main/kotlin/io/github/deficuet/unitykt/data/Object.kt). -- AssetManager & ImportContext +- UnityAssetManager & ImportContext - For each file loaded, an `ImportContext` with file name and directory will be given. An `ImportContext` contains all objects read from the file. - When load files/folder, a list of `ImportContext` will be returned. - - `AssetManager` contains all objects read from all files that are loaded through it, except `AssetBundle` objects. - - Don't forget to run the method `closeAll()` to close and release the resources used by the manager, or run the static method `closeAll()` in `AssetManager` to release resources used by **all** manager instances. + - `UnityAssetManager` contains all objects read from all files that are loaded through it, except `AssetBundle` objects. + - Don't forget to run the method `close()` to close and release the resources used by the manager, or run the static method `closeAll()` in `UnityAssetManager` to release resources used by **all** manager instances. It implements `Closeable` interface, so in Kotlin using the function `use()` would be a good idea. - Shortcuts - See [utils.kt](https://github.com/Deficuet/UnityKt/blob/main/src/main/kotlin/io/github/deficuet/unitykt/utils.kt) and [PPtrUtils.kt](https://github.com/Deficuet/UnityKt/blob/main/src/main/kotlin/io/github/deficuet/unitykt/PPtrUtils.kt) - - Should always use `PPtr.getObj()` to get the object. + - Should always use `PPtr.getObj()` or `PPtr.getObjectAs<>()` to get the object (and cast it). ## Installation -Used openJDK 11.0.10 and Kotlin Language 1.5.31. +Used openJDK 11.0.10 and Kotlin Language 1.7.20. **Note:** The decoding for texture compression of `Texture2D` that needs to call native library is available on Windows 64-bit JVM **only**. - ### Gradle @@ -87,19 +87,19 @@ libraryDependencies += "com.github.Deficuet" % "UnityKt" % "{version}" ## Export So far the objects that can export data includes: - Mesh - - `exportString` - The string with same content as exporting mesh to .obj file. + - `exportString` - A string with the same content as exporting mesh to .obj file, see [AssetStudio](https://github.com/Perfare/AssetStudio). - `exportVertices` - The data of lines starts with "v" in .obj file, grouped by Vector3. - `exportUV` - The data of lines starts with "vt" in .obj file, grouped by Vector2. - `exportNormals` - The data of lines starts with "vn" in .obj file, grouped by Vector3. - `exportFaces` - The data of lines starts with "f" in .obj file, grouped by Vector3. - Texture2D - `decompressedImageData` - Image data after decoding. Can be used to create image directly. - - `image` - A BufferedImage created from `decompressedImageData`. It is usually up-side-down. + - `image` - A BufferedImage created from `decompressedImageData`. **It is usually up-side-down**. - MonoBehaviour - `json` - Export its TypeTree as [JSONObject](https://stleary.github.io/JSON-java/index.html), could be `null`. - `jsonString` - Export its TypeTree as `String`. - TextAsset - - `text()` - The function that is used to export content in this object as `String`. A `Charset` can be passed as a parameter, by default it is `Charsets.UTF_8`. + - `text()` - The function used to export content in this object as `String`. A `Charset` can be passed as a parameter, by default it is `Charsets.UTF_8`. - Shader - `exportString` - Export as String. **Include** the Spir-V Shader data. ## Example @@ -111,29 +111,37 @@ import java.io.File import javax.imageio.ImageIO fun main() { - val manager: AssetManager = AssetManager() - val context: ImportContext = manager.loadFile("C:/path/to/AssetBundle.aab") - - //If there is no Texture2D object, IndexOutOfBoundsException will be thrown. - //You can consider the function firstOfOrNull<>() - //The data of this Texture2D object has not been read yet. - val tex: Texture2D = context.objects.firstObjectOf() - - //The object data will initialize as long as you access its properties. - ImageIO.write(tex.image, "png", File("C:/whatever/you/want/tex.png")) + UnityAssetManager().use { + val context: ImportContext = it.loadFile("C:/path/to/AssetBundle.aab") + + //If there is no Texture2D object, an IndexOutOfBoundsException will be thrown. + //You can consider the function firstOfOrNull<>() + //The data of this Texture2D object has not been read yet. + val tex: Texture2D = context.objects.firstObjectOf() + + //The object data will initialize as long as you access its properties. + ImageIO.write(tex.image, "png", File("C:/whatever/you/want/tex.png")) + + //The manager will automatically close. + } - val anotherManager = AssetManager() - //Loading configurations - //It will not influence the configurations of previous manager. - //The files and objects loaded by this manager will not show in previous manager as well. - anotherManager.loadFolder("C:/foo/bar") { - offsetMode = OffsetMode.MANUAL - manualIgnoredOffset = 217 + // Instantiate another manager + UnityAssetManager().use { + //Loading configurations + //It will not influence the configurations of previous manager. + //The files and objects loaded by this manager will not show in previous manager as well. + it.loadFolder("C:/foo/bar") { + offsetMode = OffsetMode.MANUAL + manualIgnoredOffset = 217 + } + //The manager holds all the objects loaded through it, except those AssetBundle objects, their PathID is usually 1. + println(it.objects.firstObjectOf().exportString) } - println(anotherManager.objects.firstObjectOf().exportString) } ``` ## Changelog +- ### 2022.12.23 + - Catch up on the newest version of AssetStudio. Try to optimize memory use, re-design some structures. - ### 2022.02.20 - Publish on JitPack - ### 2022.02.19