Skip to content

README.ja.md

Latest commit

 

History

History
276 lines (214 loc) · 11.3 KB

README.ja.md

File metadata and controls

276 lines (214 loc) · 11.3 KB

KoikatuCharaLoader

このプログラムは、コイカツ・エモクリ・ハニカム・サマすく・アイコミのキャラカード・シーンデータをPythonで読み込む・書き込むためのライブラリです。

Downloads Open In Colab Ask DeepWiki

インストール

PyPIからインストールできます。

$ pip install kkloader

これでうまく入らないようでしたら以下のコマンドを試してみてください。

$ python -m pip install kkloader

ちょっとだけこのモジュールを試してみたい場合は、上の"Open In Colab"をクリックすることで、Colab上で実行させることもできます。

簡単な使い方

$ python
>>> from kkloader import KoikatuCharaData # モジュールを読み込む
>>> kc = KoikatuCharaData.load("./data/kk_chara.png") # キャラデータを読み込む
>>> kc
KoikatuCharaData(product_no=100, header='【KoiKatuChara】', version='0.0.0', name='白峰 一乃 ( かずのん )', blocks=['Custom', 'Coordinate', 'Parameter', 'Status'], has_kkex=False, original_file_path='/path/to/data/kk_chara.png')
>>> kc["Parameter"]["nickname"] # ニックネームを表示する
'かずのん'
>>> kc["Parameter"]["nickname"] = "ちかりん" # ニックネームを"ちかりん"にする
>>> kc.save("./kk_chara_modified.png") # `kk_chara_modified.png`へ出力する

簡単!

使用できるクラスの一覧

  • 読み込みと書き込み両方に対応
    • KoikatuCharaData
    • KoikatuSceneData
    • EmocreCharaData
    • HoneycomeCharaData
    • SummerVacationCharaData
    • SummerVacationSaveData
    • AicomiCharaData
    • HoneycomeSceneData (DigitalCraft全般に対応)
  • 読み込みのみ対応
    • KoikatuSaveData
    • EmocreMapData
    • EmocreSceneData

いずれのクラスも from kkloader import KoikatuCharaData のようにインポートし、 .load(filename) のようにファイルを読み込むことができます。

ブロックデータについて

コイカツのキャラデータは"ブロックデータ"というデータのかたまりから成っています。 ぞれぞれのブロックデータの中に、例えば服装の設定がまとまって入っていたり、体型の設定が入っていたりするわけです。

コイカツのキャラデータに入っているのは基本的に下記のブロックデータです。

ブロックデータの名前 説明
Custom 顔の形・体型・髪型の設定が入っています。
Coordinate 服装とアクセサリーの設定が入っています。
Parameter 名前や誕生日などの設定が入っています。
Status 着衣状態等の変数が入っていますが、ゲーム中にどう影響あるかは不明です。
About 作者IDとデータIDが入っています。コイカツサンシャインから追加されています。
KKEx MODのデータが色々と入っているデータブロックです。

具体的にどのブロックデータが含まれているかは KoikatuCharaData クラスの blockdata 変数を見れば分かります。

>>> kc.blockdata
['Custom', 'Coordinate', 'Parameter', 'Status']

また、unknown_blockdata には未対応のフォーマットで書かれているブロックデータの名前が入っています。

ブロックデータへのアクセス

ブロックデータへは KoikatuCharaData クラスのメンバ変数としてアクセスできる他、辞書型として読み込むこともできます。

>>> kc.Custom
<kkloader.KoikatuCharaData.Custom object at 0x7f406bf18460>
>>> kc["Custom"]
<kkloader.KoikatuCharaData.Custom object at 0x7f406bf18460>

つまり、この2行はどちらも同じ kc.Custom へアクセスしています。

変数を探す

こちらのサイトにて、このプログラムによるキャラクター情報の表示をブラウザ上で試すことができます。変えたい変数を探す場合は、まずはここから目星をつけるのがよいでしょう。

CLI上では prettify メソッドを使えば、ブロックデータに含まれている変数の一覧が見やすい形式で出力されます。

>>> kc["Custom"].prettify()
{
  "face": {
    "version": "0.0.2",
    "shapeValueFace": [
      ...
    ],
    "headId": 0,
    "skinId": 0,
    "detailId": 0,
    "detailPower": 0.41674190759658813,
    ...

KKEx内にあるMessagePackデータについて

KKEx には、さらに内部でMessagePackでエンコードされた bytes 型のデータが含まれていることがあります。
このプログラムは、KKEx.NESTED_KEYS に挙げられているプラグインについて追加でこのMessagePackのデータをシリアライズ/デシリアライズします。

JSONファイルへ出力する

save_jsonメソッドを使えばキャラのデータをまとめてJSONファイルへ出力できます。

from kkloader import KoikatuCharaData

k = KoikatuCharaData.load("./data/kk_chara.png")
k.save_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,
...

save_jsonメソッドの引数に include_image=True をつけると、base64エンコードされた画像ファイルがJSONの中に出力されます。

使用例

キャラ名を変更する

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")

キャラの身長を50にする

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")

エモクリのキャラデータをコイカツのキャラデータに変換する

sampleフォルダにある ec_to_kk.py が参考になると思います。

ただこのプログラムが使いたいだけなのであれば、このサイト から同じ処理をブラウザ上で実行することができます。

シーンデータを読み込む

walk()メソッドを使うと、子オブジェクト（キャラクターに装着されたアイテムやフォルダ内のオブジェクトなど）を含む全てのオブジェクトを再帰的に列挙できます。

from kkloader import KoikatuSceneData

scene = KoikatuSceneData.load("./data/kk_scene.png")

# 全オブジェクトをシンプルに列挙
for key, obj in scene.walk():
    obj_type = obj["type"]
    print(f"Key: {key}, Type: {obj_type}")

# 深さ情報付きで列挙（階層構造の可視化に便利）
for key, obj, depth in scene.walk(include_depth=True):
    indent = "  " * depth
    obj_type = obj["type"]
    print(f"{indent}[depth={depth}] Key: {key}, Type: {obj_type}")

# typeを指定してのイテレーションも可能
for key, obj in scene.walk(object_type=KoikatuSceneData.CHARACTER):
    print(f"Character Key: {key}")

オブジェクトタイプ: 0=Character, 1=Item, 2=Light, 3=Folder, 4=Route, 5=Camera, 7=Text

シーンデータからキャラクターデータを抽出する

上記の walk() メソッドを使うことで簡単に書けます。

import copy

from kkloader import KoikatuSceneData

# シーンデータのロード
scene = KoikatuSceneData.load("./data/kk_scene.png")

# シーンに含まれるキャラオブジェクトのみをイテレーションする
for _, obj_info in scene.walk(object_type=KoikatuSceneData.CHARACTER):
    chara = obj_info["data"]["character"]

    # キャラデータの顔のサムネイル画像をpngデータにする
    chara.image = copy.deepcopy(chara.face_image)

    # キャラデータの保存
    chara.save("./data/{}.png".format(name))

その他

このモジュールを使った色々な例が このリポジトリ にあり、さらに このサイト で使うこともできます。

サンプルスクリプトの使い方

samples/ フォルダにあるスクリプトはuvで環境を作った後 uv run で実行するのが便利です。

KK/EC間の変換

このサイト を使えば、Python環境を用意することなくブラウザ上で変換できます。

コイカツ → エモクリ変換:

uv run samples/kk_to_ec.py <入力ファイル> <出力ファイル>

エモクリ → コイカツ変換:

uv run samples/ec_to_kk.py <入力ファイル> <出力ファイル>

例:

uv run samples/kk_to_ec.py ./data/kk_chara.png ./data/converted.png
uv run samples/ec_to_kk.py ./data/ec_chara.png ./data/converted.png

コイカツシーンデータからキャラデータを抽出する

シーンファイルに含まれる全キャラクターを指定ディレクトリへ保存します。

uv run samples/salvage_character_from_scene.py <シーンファイル> <出力ディレクトリ>

例:

uv run samples/salvage_character_from_scene.py ./data/kk_scene.png ./data/

開発に参加する

Python 3.11とuvコマンドが必要です(このページを参考にインストールできます)。

  1. このリポジトリをフォークし、ローカルにpullします。
  2. make installしてuvを使って環境がセットアップされます。
  3. 新しくブランチを切り、コードに変更を加えます。
  4. make formatとmake checkを行い、変更を加えたコードをフォーマット&チェックします。
  5. make checkがエラーなく終わったなら、コードをpushしこのリポジトリにプルリクエストを出してください。

謝辞

連絡先

@tropical_362827