{
    "info": {
        "author": "Manoel <godzil> Trapier",
        "author_email": "wssplashbuilder@godzil.net",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 2 - Pre-Alpha",
            "Environment :: Console",
            "License :: OSI Approved :: BSD License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3"
        ],
        "description": "WonderSwan SplashBuilder\n========================\n\nThis tool is made to help you build custom boot splash for the Bandai WonderSwan Color and SwanCrystal.\n\n\n# **Warning**:\nInstalling a custom bootsplash on your own console __is at your own risk__. It is really easy to brick your\nconsole if something is wrong, and there is only one way to recover from that which is to have a special cartridge that\nforbid the user bootsplash to run (look further in the document on what are the requirement for that).\n\n**ALWAYS EXTENSIVELY TEST WITH AN EMULATOR BEFORE EVEN TRYING ON A REAL CONSOLE.**\n\n\nThere is also currently (as of 2019-09-08) no tool to install a custom bootsplash in your WonderSwan EEPROM.\nI will eventually provide such a tool at a later point.\n\n\n#### Installing SplashBuilder\n\nYou first need to install this tool. You can either use directly from the github sources, or (recommended) install\nusing pip:\n\n```\npip install splashbuilder\n```\n\nSplashBuilder is build using Python3 and some Linux distribution may force you to use `pip3` instead of `pip` to\ninstall using Python 3.\n\nYou also need [https://www.nasm.us/](`nasm`) to be installed if you want to have your own code running in your bootsplash as a boot splash\ninclude some code.\n\n#### How to make a bootsplash\n\nTO BE FINISHED\n\n\n\n\n#### Some technical info about the boot splashes\n\nThe basis of the bootsplash is a structure containing certains fields:\n```C\nstruct bootsplash_t\n{\n   uint8_t padding[3];\n   uint8_t consoleFlags;\n   uint8_t consoleNameColor;\n   uint8_t padding2;\n   uint8_t size;\n   uint8_t startFrame;\n   uint8_t endFrame;\n   uint8_t spriteCount;\n   uint8_t paletteFlags;\n   uint8_t tilesCount;\n   uint16_t paletteOffset;\n   uint16_t tilesetOffset;\n   uint16_t tilemapOffset;\n   uint16_t horizontalTilemapDestOffset;\n   uint16_t verticalTilemapDestOffset;\n   uint8_t tilemapWidth;\n   uint8_t tilemapHeight;\n   uint32_t splashCodePointer;\n   uint8_t consoleNameHorizontalPosX;\n   uint8_t consoleNameHorizontalPosY;\n   uint8_t consoleNameVerticalPosX;\n   uint8_t consoleNameVerticalPosY;\n   uint8_t padding3[2];\n   uint16_t soundSampleOffset;\n   uint16_t soundChannelDataOffset[]\n};\n```\n\nthat you will find in the internal EEPROM starting from 80h in 8bit mode or 40h in 16bit access mode (that how the\nWonderSwan is accessing the EEPROM)\n\nHere are a description of the fields\n\n* `consoleFlags`: This byte store some information about the console configuration:\n    * `bit 7`: 1 = Custom boot splash enabled\n    * `bit 6`: 1 = High contrast mode (WonderSwan Color only)\n    * `bit 5-2`: Ignored\n    * `bit 1-0`: Default volume level\n* `consoleNameColor`: This byte set the default color used by the sprites for the console name.\nOnly value from 0 to 15 are valid. Here is the list of available colors (order is left to right, top to bottom)\n\n![ConsoleNameColors](doc/ConsoleNameColors.png)\n* `size`: The size of the bootsplash. Only two valid values: 0 a 1. 0 mean the size is up to 1BDh, 1 mean the size\nis up to 3BDh. You can safely leave that value to 1.\n* `startFrame` and `endFrame`: The code in the bootrom count the number of frames from 0 to 255. Both value tell it\nwhen your splash need to be displayed, and when it end. When it reach the end, the game is going to be booted.\n* `spriteCount`: The number of sprite your bootsplash use.\n* `paletteFlags`:\n    * `bit 7`: Bootsplash BPP mode. 0 = 1BPP, 1 = planar 2BPP\n    * `bit 6-5`: ignored\n    * `bit 4-0`: number of palettes defined in the bootsplash. For some bizarre reason, the bootrom allow values up to\n    32 which make no sense knowing that the hardware support only up to 16 palettes.\n* `tilesCount`: The number of tiles your bootsplash provide.\n* `paletteOffset`, `tilesetOffset`, `tilemapOffset`: offset in the bootsplash file where the palette, tileset and\ndefault tilemap will be found.\n* `horizontalTilemapDestOffset`: The offset (as in address) in SCREEN1 where the tilemap has to be copied when the\nconsole start in horizontal mode.\n* `verticalTilemapDestOffset`: The offset (as in address) in SCREEN1 where the tilemap has to be copied when the\nconsole start in vertical mode.\n* `tilemapWidth`: the width of your default tilemap\n* `tilemapHeight: the height of your default tilemap`\n* `splashCodePointer`: The far pointer to the code you include in the bootsplash. **Warning** it is a `far` pointer, so\nboth offset and segment need to be given, but the segment is fixed and need to be 0600h. Your code also need to be valid\nand return with a `retf` (CBh) instruction and not a `ret` (C3h).\n* `consoleNameHorizontalPosX`, `consoleNameHorizontalPosY`: The position in pixel in horizontal mode of the console name\n* `consoleNameVerticalPosX`, `consoleNameVerticalPosY`: The position in pixel in vertical mode of the console name\n* `soundSampleOffset`: The offset in the bootsplash file where the 4 waveform are set for each audio channel\n* `soundChannelDataOffset[]` This is a list of offset for the data used to play notes on each audio channel. This list\nneed to be ended with FFFFh after the last offset is given. so for 2 channel used, you will get\n```\nXXXXh, YYYYh, FFFFh\n```\n\nThen it is followed by each block that are listed by the header:\n- Palette\n- Tileset\n- Tilemap\n- Audio waveforms\n- Audio data for each channel used\n- VBlank code\n\n##### IRAM Memory map used by the boot rom for the bootsplash:\n\n```\n0000h - 07FFh: internal data for the bootrom. >> Don't touch it\n0800h - 0FFFh: Tilemap for Screen 1\n1000h - 17FFh: Tilemap for Screen 2\n1800h - 1FFFh: Sprite list\n2000h - 3FFFh: 2BPP Tileset\n4000h - 5FFFh: N/A\n6000h - 6FFFh: Boot splash data >> Don't touch it\n7000h - 7FFFh: Bootsplash data\n8000h - FDFFh: N/A\nFE00h - FFFFh: Palette data\n```\n\nThe bootsplash data region contain by default some informations which is better to not touch:\n\n`7000h`: store the screen orientation\n\n##### Tileset BPP\nIt may sounds weird, but the bootsplah support one well know mode, the planar 2bpp, but also a 1bpp mode which in theory\nthe console does not support. For that the bootroom will automatically convert it to the planar 2bpp mode. This mode\nallow to save space if you don't need 4 colors per tiles.\n\nThe palette definition will also change depending on the BPP set. You only need to provide two colors per palette in\n1BPP mode, and four in 2BPP mode.\n\n##### How the segment register in the vblank code\n```\nCS = 0600h\nDS = 0600h\nES = ??\nSS = 0000h\n```\n__DO NOT CHANGE THEM UNLESS YOU ARE SURE TO RESTORE THEM__\n\n##### Sounds data channel format\nEach \"note\" are defined by a 32bit value:\n```\nDDVVPPPP:\nDD   = duration (8 bit) (in vblank frame)\nVV   = Volume (8bit)\nPPPP = Pitch (16bit)\n```\nIf pitch bit 7 is set then the channel is stopped.\n\n\n#### How to recover a bricked WonderSwan\n**Q:** HELP, I made booboo and tried my bootsplash on real hardware and bricked my Wonderswan.\n\n**A:** Well it is not like if I haven't put a warning at the beginning of this file.\n\nThere is two way to recover from that. And both are not easy.\n\nThe first method is to use some external hardware to write to the internal EEPROM and change the consoleFlag byte to\ndisable the Custom boot splash. Easy some would say, but you need to open your console, connect some wire\n(but probably you will need to desolder the chip) and use some tool to write to the EEPROM. Not something that everyone\ncan do.\n\nThe second method, which will be easier in the end, but there is currently no such tool available, a cartridge can force\nthe bootrom to ignore a custom boot splash. Bandai/Koto was wise enough to add that, but there is no commercial games\n(including the WonderWitch) which are configured to do that.\nThere is also at the moment of writing no Flash cart that allow that.\nThe bit that need to be set to 1 is part of the cartridge metadata.\nIn the last 16 bytes you will find the reset vector and some information about the game:\n```\n00h - 04h: JMP FAR instruction for the reset vector\n05h      : ???\n06h      : Publisher ID\n07h - 08h: Game IO\n09h      : Game revision\n0Ah      : ROM size\n0Bh      : Save type / size\n0Ch - 0Dh: Cart flags\n0Eh - 0Fh: ROM CRC\n```\n\nThe byte 5 is a bit of a weird byte here:\n- `bit 7`: Set = ignore custom bootsplash\n- `bit 6-4`: ignored\n- `bit 3-0`: if set the console refuse to boot. Why? (I suspect this is related with Devkit cartridges)\n\n_To WonderSwan flash cart manufacturer_: I highly recommend that your flash cart have the possibility to set the bit 7\nof byte 5 to 1, either permanently, or in any way that does not involve using a console, so people could recover from a\nbadly installed bootsplash.\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/godzil/splashbuilder",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "splashbuilder",
        "package_url": "https://pypi.org/project/splashbuilder/",
        "platform": "",
        "project_url": "https://pypi.org/project/splashbuilder/",
        "project_urls": {
            "Homepage": "https://github.com/godzil/splashbuilder"
        },
        "release_url": "https://pypi.org/project/splashbuilder/0.0/",
        "requires_dist": null,
        "requires_python": ">=3.6",
        "summary": "A tool to build WonderSwan Color boot splash",
        "version": "0.0"
    },
    "last_serial": 5945630,
    "releases": {
        "0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "2059fc914b62643d0ea57868f78f20bb",
                    "sha256": "c111926030766ebf5061f1a7daaac18d75b6b9ad2cd500c6e5542d5f0c3fe42f"
                },
                "downloads": -1,
                "filename": "splashbuilder-0.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "2059fc914b62643d0ea57868f78f20bb",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.6",
                "size": 11055,
                "upload_time": "2019-10-08T16:38:29",
                "url": "https://files.pythonhosted.org/packages/c4/a7/90a0dd3bc01b936d763088ecb41eb0ebef25d7c347d3cdf3150badf18931/splashbuilder-0.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "f0b1be0e3c1f219be35555916668232e",
                    "sha256": "13da07b0d68662f4a03b42971ea5368db77b0e6b4c5c66fe54978a188fcf7752"
                },
                "downloads": -1,
                "filename": "splashbuilder-0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "f0b1be0e3c1f219be35555916668232e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 11461,
                "upload_time": "2019-10-08T16:38:31",
                "url": "https://files.pythonhosted.org/packages/df/b9/f2f313e8d6d4779f3c1da981ff79965426578c230e50bd158690087b337d/splashbuilder-0.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "2059fc914b62643d0ea57868f78f20bb",
                "sha256": "c111926030766ebf5061f1a7daaac18d75b6b9ad2cd500c6e5542d5f0c3fe42f"
            },
            "downloads": -1,
            "filename": "splashbuilder-0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2059fc914b62643d0ea57868f78f20bb",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 11055,
            "upload_time": "2019-10-08T16:38:29",
            "url": "https://files.pythonhosted.org/packages/c4/a7/90a0dd3bc01b936d763088ecb41eb0ebef25d7c347d3cdf3150badf18931/splashbuilder-0.0-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "f0b1be0e3c1f219be35555916668232e",
                "sha256": "13da07b0d68662f4a03b42971ea5368db77b0e6b4c5c66fe54978a188fcf7752"
            },
            "downloads": -1,
            "filename": "splashbuilder-0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "f0b1be0e3c1f219be35555916668232e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 11461,
            "upload_time": "2019-10-08T16:38:31",
            "url": "https://files.pythonhosted.org/packages/df/b9/f2f313e8d6d4779f3c1da981ff79965426578c230e50bd158690087b337d/splashbuilder-0.0.tar.gz"
        }
    ]
}