effect_wan support (#549)

* effect_wan

* working export

* support imgtype 3

* linting fixes

* more linting and documentation

* ruff for sheets

* lint and ruff for None comparisons

* add TODO for duration

---------

Co-authored-by: Marco Köpcke <[email protected]>

skytemple_files/graphics/effect_wan/README.rst

@@ -0,0 +1,51 @@
+wan File Format for VFX
+===============
+
+The file ``/EFFECT/effect.bin`` contains vfx used for dungeon battle, weather effects, and some ground mode vfx.
+
+The file contains 293 effect entries.  They contain the following data:
+
+* effect0000: Only contains animation data.  Relies on the Image data of 00292 and loaded at the start.
+* effect0001: Generic effects loaded at the start.
+* effect0002-0259: VFX for attacks and certain ground mode cutscenes.
+* effect0260-00267: VFX for ground mode cutscenes.
+* effect0268-00289: Not WAN.  Used for screen effects in moves and cutscenes.
+* effect0290-00291: Not Sir0
+* effect0292: Only contains image data.  The palette is loaded at the start and sticks around to be used by various other effects in the list.
+
+This parser deals with only the WAN files.
+
+Each slot contains one or more animations. See the `Project Pokémon documentation`_ for more details.
+
+Usage
+-----
+Use the class ``EffectWanHandler`` of the ``handler`` module, to open and save
+models from binary data. The model that the handler returns is in the
+module ``model``.
+
+To export a WanFile to sheets, use ``ExportSheets`` in the ``sheets`` module.
+``ExportSheets`` requires a base effect model.  In unmodded EoS, this is effect292.
+
+Import is currently not supported.
+
+
+File Format
+-----------
+
+See `Project Pokémon documentation`_.
+
+Credits
+-------
+Without the following people, this implementation wouldn't have been possible:
+
+- psy_commando_ (C++ implementation, documentation and most of the research work!)
+Based on following documentations:
+
+- `Project Pokémon documentation`_ (Documentation mostly adapted from there!)
+- `psy_commando Dropbox`_
+
+
+.. Links:
+
+.. _Project Pokémon documentation:  https://projectpokemon.org/home/docs/mystery-dungeon-nds/wan-format-for-effectbin-r156/
+.. _psy_commando Dropbox:           https://www.dropbox.com/sh/8on92uax2mf79gv/AADCmlKOD9oC_NhHnRXVdmMSa?dl=0

skytemple_files/graphics/effect_wan/handler.py

@@ -0,0 +1,45 @@
+#  Copyright 2020-2024 Capypara and the SkyTemple Contributors
+#
+#  This file is part of SkyTemple.
+#
+#  SkyTemple is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  SkyTemple is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with SkyTemple.  If not, see <https://www.gnu.org/licenses/>.
+from __future__ import annotations
+
+from skytemple_files.common.types.data_handler import DataHandler
+from skytemple_files.common.util import OptionalKwargs
+from skytemple_files.graphics.effect_wan.model import WanFile
+from skytemple_files.graphics.effect_wan.sheets import ExportSheets
+
+
+class EffectWanHandler(DataHandler[WanFile]):
+    @classmethod
+    def deserialize(cls, data: bytes, **kwargs: OptionalKwargs) -> WanFile:
+        from skytemple_files.common.types.file_types import FileType
+
+        sir0_data = FileType.SIR0.deserialize(data)
+        wan = WanFile()
+        wan.ImportWan(sir0_data.content, sir0_data.content_pointer_offsets, sir0_data.data_pointer)
+        return wan
+        # TODO: do this the normal way once there's a way to pass in pointer lists to the effectWAN file
+        return FileType.SIR0.unwrap_obj(FileType.SIR0.deserialize(data), WanFile)  # type: ignore
+
+    @classmethod
+    def serialize(cls, data: WanFile, **kwargs: OptionalKwargs) -> bytes:
+        from skytemple_files.common.types.file_types import FileType
+
+        return FileType.SIR0.serialize(FileType.SIR0.wrap_obj(data))  # type: ignore
+
+    @classmethod
+    def export_sheets(cls, out_dir: str, wan: WanFile) -> None:
+        return ExportSheets(out_dir, wan)  # type: ignore