Metadata-Version: 2.1
Name: kkloader
Version: 0.1.3
Summary: a simple deserializer / serializer for Koikatu / EmotionCreators data.
Home-page: https://github.com/great-majority/KoikatuCharaLoader
Author: great-majority
Author-email: yosaku.ideal+github@gmail.com
Requires-Python: >=3.7,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: msgpack (>=1.0.2,<2.0.0)
Description-Content-Type: text/markdown

# KoikatuCharaLoader
A simple deserializer / serializer for Koikatu / EmotionCreators character data.

# Installation
You can install this module from [PyPI](https://pypi.org/project/kkloader/).
```
$ pip install kkloader
```
If this does not work, try the following command (for Windows users, maybe).
```
$ python -m pip install kkloader
```

# Basic Usage
```python
$ python
>>> from kkloader import KoikatuCharaData # Load a module.
>>> kc = KoikatuCharaData.load("./data/kk_chara.png") # Load a character data.
>>> kc["Parameter"]["nickname"] # Print character's nickname.
'かずのん'
>>> kc["Parameter"]["nickname"] = "chikarin" # Renaming nickname.
>>> kc.save("./kk_chara_modified.png") # Save to `kk_chara_modified.png`.
```
that's it :)

# Mechanism of the Blockdata

A character data of koikatu consists of some *blockdata*.
The *blockdata* is a collection of character parameters.
A typical Koikatsu character data contains the following blockdata:

| name of blockdata | description                                                  |
| ----------------- | ------------------------------------------------------------ |
| Custom            | Values for the character's face, body, and hairstyle.        |
| Coordinate        | Values for clothes and accessories worn by characters.       |
| Parameter         | Values for character names, birthdays, preferences, etc.     |
| Status            | Values for clothed states, etc. (I'm not sure how they are used in the game) |

You can check which block data exists from `blockdata` in KoikatuCharaData.
```
>>> kc.blockdata
['Custom', 'Coordinate', 'Parameter', 'Status']
```
If there is block data in an unknown format, it can be checked with `unknown_blockdata`.
```
>>> kk_mod_chara.unknown_blockdata
['KKEx']
```
`KKEx` is included in the character data saved by Koikatsu with MOD.

### Find Variables

By using the `prettify` method, the contents of the variables contained in the block of data will be displayed in an easy-to-read format.
This is useful to find which variables exists.
```
>>> kc["Custom"].prettify()
{
  "face": {
    "version": "0.0.2",
    "shapeValueFace": [
      ...
    ],
    "headId": 0,
    "skinId": 0,
    "detailId": 0,
    "detailPower": 0.41674190759658813,
    ...
```

# Export to JSON file
```
from kkloader import KoikatuCharaData

k = KoikatuCharaData.load("./data/kk_chara.png")
k.save_json("data.json") 
```

`data.json`
```data.json
{
  "product_no": 100,
  "header": "\u3010KoiKatuChara\u3011",
  "version": "0.0.0",
  "Custom": {
    "face": {
      "version": "0.0.2",
      "shapeValueFace": [
        0.5403226017951965,
        1.0,
        0.2016129046678543,
        0.0,
        0.22580644488334656,
        0.0,
        0.0,
        0.1794193685054779,
        0.0,
...
```
If you add `include_image=True` to the argument of `save_json`, base64-encoded images will be included in json.

# Recipes

### Rename Character's Name
```python
from kkloader import KoikatuCharaData

k = KoikatuCharaData.load("./data/kk_chara.png")
k["Parameter"]["lastname"] = "春野"
k["Parameter"]["firstname"] = "千佳"
k["Parameter"]["nickname"] = "ちかりん"
k.save("./data/kk_chara_modified")
```

### Set the Height of Character to 50
```python
from kkloader import KoikatuCharaData

k = KoikatuCharaData.load("./data/kk_chara.png")
k["Custom"]["body"]["shapeValueBody"][0] = 0.5
k.save("./data/kk_chara_modified.png")  
```

### Remove Swim Cap
```python
from kkloader import KoikatuCharaData

k = KoikatuCharaData.load("./data/kk_chara.png")
for i,c in enumerate(k["Coordinate"]):
    for n,p in enumerate(c["accessory"]["parts"]):
        if p["id"] == 5:
            k["Coordinate"][i]["accessory"]["parts"][n]["type"] = 120
k.save("./data/kk_chara_modified.png")  
```

### Remove Under Hair
```python
from kkloader import KoikatuCharaData
kc = KoikatuCharaData.load("./data/kk_chara.png")
kc["Custom"]["body"]["underhairId"] = 0
kc.save("./data/kk_chara_modified.png")
```

# Acknowledgements
- [martinwu42/pykoikatu](https://github.com/martinwu42/pykoikatu)
