├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | This is free and unencumbered software released into the public domain. 2 | 3 | Anyone is free to copy, modify, publish, use, compile, sell, or 4 | distribute this software, either in source code form or as a compiled 5 | binary, for any purpose, commercial or non-commercial, and by any 6 | means. 7 | 8 | In jurisdictions that recognize copyright laws, the author or authors 9 | of this software dedicate any and all copyright interest in the 10 | software to the public domain. We make this dedication for the benefit 11 | of the public at large and to the detriment of our heirs and 12 | successors. We intend this dedication to be an overt act of 13 | relinquishment in perpetuity of all present and future rights to this 14 | software under copyright law. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 20 | OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 21 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 22 | OTHER DEALINGS IN THE SOFTWARE. 23 | 24 | For more information, please refer to 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | A short guide to the Krkr2/KrkrZ ecosystem for the western reverser/translator/developer. 2 | Wherever the document names the author of a system, you should mentally append `(and contributors)`. 3 | Comments and pull requests welcome. 4 | 5 | ### Disclaimer 6 | 7 | This document effortlessly mixes my own conjecture and estimates with actual documented fact. 8 | Don't take any of this as holy scripture. This is just a starting point. Let me know where I'm wrong. 9 | 10 | ## How to edit Shift-JIS *and* UCS-2 encoded script without JP system locale 11 | 12 | Use [Sublime Text](https://www.sublimetext.com/) with the [ConvertToUTF8](https://github.com/seanliang/ConvertToUTF8) plugin. 13 | Despite its name, this plugin actually also adds transparent support for SJIS text encoding, which Sublime Text lacks natively. 14 | 15 | # Systems 16 | 17 | ## KRKR2 / KiriKiri2 18 | KRKR2 aka KiriKiri2 is a game engine that executes its own TJS script language, somewhat similar to JavaScript. 19 | It was created and developed by W.Dee as a rewrite of their original KiriKiri engine. 20 | KRKR2 has been thoroughly outdated for well over a decade, and is generally not used by new projects. 21 | - KRKR2 Source tree: https://github.com/krkrz/krkr2/tree/master/kirikiri2/trunk (Time-frozen/Read-only copy) 22 | 23 | ## KRKRZ / KiriKiriZ 24 | KRKRZ however is a more modern fork of KRKR2 and is still widely used and supported. 25 | KRKRZ features a separate backwards compatibility layer for Krkr2 scripts called `k2compat`. 26 | This document in general will refer and link to KRKRZ versions of plugins etc, where available. 27 | - KRKRZ Source tree: https://github.com/krkrz/krkrz 28 | - KRKRZ Docs: http://krkrz.github.io/documents/ 29 | 30 | ## K2Compat 31 | A backwards compatibility layer to allow KRKR2 scripts to run under KRKRZ. 32 | - K2Compat Source tree: https://github.com/krkrz/Krkr2Compat 33 | 34 | ## KAG3 35 | KAG3 or "Kirikiri Adventure Game" is a scene and UI building system written by W.Dee in TJS for KRKR2/KRKRZ. 36 | KAG3 runs `.ks` files and is the base system on top of which almost all KiriKiri VNs are built. 37 | - KAG3 Docs: http://kirikirikag.sourceforge.net/contents/index.html 38 | - KAG3 Source for KrkrZ: https://github.com/krkrz/kag3 39 | 40 | ## KAGEX 41 | KAGEX is an extension of KAG3 by [wtnbgo](https://github.com/wtnbgo)/Watanabe Go. 42 | Some other extensions exist for KAG3 which are incompatible/mutually exclusive with KAGEX, but in practice 43 | KAGEX is by far the most common choice for developers. You can tell whether a game uses KAGEX by the 44 | existence of a plugin called `KAGParserEx.dll` or multiple system scripts named `KAGEnv*.tjs`. 45 | KAGEX has been documented quite extensively by [sakano](https://github.com/sakano)/Naoya Komatsu. 46 | - KAGEX3 Source tree: https://github.com/krkrz/krkr2/tree/master/kirikiri2/branches/kag3ex3 (Frozen copy) 47 | - KAGEX3 Class diagram: http://blog-imgs-43.fc2.com/k/a/s/kasekey/kag3ex3_class.png 48 | - KAGEX Docs: https://biscrat.com/krkr/docs/kagex/contents/ 49 | - KAGEX Book: https://github.com/sakano/krkr_archives/raw/master/doc/kagex_book/KagexBook.pdf 50 | - Sakano's blog/articles on KAGEX and related usage: https://biscrat.com/blog/kagex-articles/ 51 | 52 | # Glossary 53 | - **TJS**: The script language executed by the KiriKiri engines. Similar to JavaScript, but unique. 54 | File extension is `.tjs`, but the file itself can be either a plaintext script that is compiled on the fly by the engine, 55 | or it can be a precompiled binary file which contains just the assembled TJS virtual machine instructions. 56 | Apart from basic string replacements, there are no reliable or convenient ways to edit compiled TJS script. 57 | Disassemblers let you see what the TJS script does, but the disassembly cannot be parsed back into runnable TJS. 58 | A decompiler can be found within the [Furikiri](https://github.com/UlyssesWu/Furikiri) project and run from the command line via its Girigiri interface, 59 | but this only works for relatively simple and short TJS files. The success rate for decompilation of TJS files found 60 | in the wild is in my experience about 20%. If you need to modify a precompiled TJS script (other than the string replacement, 61 | which can be done with [ScnEditorGUI](https://github.com/marcussacana/KrKrZSceneManager)) and the decompiler fails, generally you're SOL. 62 | Thankfully, however, most TJS that ships with games is actually unmodified open source and can be found online. 63 | sakano has written a TJS syntax highlight for Visual Studio Code, available [here](https://marketplace.visualstudio.com/items?itemName=Biscrat.tjs-vscode). 64 | - **KAG**: The visual novel/adventure game system that takes care of basic UI and UX, layered rendering and 65 | game state machinery for the game developer's convenience. KAG is written entirely in TJS, and is itself 66 | a processor for KS (KAG Script) files. KAG Script is a simple tag-based language, and a whole game can be 67 | written in KS alone. Often, however, developers will use additional systems for ease development on top of KAG, 68 | which relegates the KS scripts to mostly serve the menu and UI role. 69 | One such example is the commercial`?` SCN scene format and parser by [M2 Co. Ltd.](https://www.mtwo.co.jp/) 70 | - **KS**: KAG Script file format. Very simple text-based script that uses a tag system and rudimentary 71 | assignment and comparison operators to create interactivity. Usually a game's menu, config and staff roll 72 | at least are written in KS. However older and smaller VNs in particular can also be written entirely in KS. 73 | - **AMV**: A custom video file format which features an alpha channel, implemented by plugin `AlphaMovie.dll`. 74 | - **SCN**: TLDW 75 | - **PSB**: TLDW 76 | - **TLG**: Image file format used for foreground sprites, i.e. character art. 77 | Convertible to and from PNG by tools like [GARbro](https://github.com/morkt/GARbro) and the [FreeMote PSB Toolkit](https://github.com/UlyssesWu/FreeMote). 78 | - **SINFO**: A tabulated text file that maps names for characters' attire, expressions etc. to the corresponding images. 79 | - **SOL**: Shit Outta Luck 80 | 81 | # Dialogue in KAG/KAGEX 82 | Games built on the KAG system have multiple different methods of implementing their dialogue parsing. 83 | I'll probably document the actual possible *sources* of the dialogue sometime later; 84 | For now I'm just adding a word about text formatting. 85 | 86 | ## Fonts and default formatting 87 | For many VNs their dialogue stays visually rather static throughout, and might be monospaced. 88 | Monospacing is natural for Japanese kana & kanji, but should have no place in western dialogue text. 89 | 90 | In fact, shipping a game with monospaced dialogue in English ought to be outlawed. 91 | 92 | Default text formatting is usually set in `default.tjs`, so look there first and see if your issues can be solved 93 | by a simple font change. A list of embedded font files to load is usually defined in `embfontlist.tjs`. 94 | The available font names used to refer to faces within scripts, then, are the `Dictionary` keys from that file. 95 | 96 | You'll figure it out. 97 | 98 | ## In-line commands and effects 99 | As for in-line effects like colors, alignment, speed changes, awaits and so on, there are a couple ways 100 | a KAG-based game might parse them. The first is `textrender.dll`. This DLL exposes a TJS class called 101 | `TextRenderBase`, on top of which a corresponding `textrender.tjs` implements a proxy class called `TextRender`. 102 | I've documented the syntax for `TextRender`-based text formatting in a sister repository. 103 | 104 | A script-only version of `textrender.tjs` which does not utilize the DLL also exists and ships with some games. 105 | 106 | The other possibility is `texttagconverter.tjs`. This script processes a syntax similar to that of `TextRender` 107 | into KAG script tags before the text is fed into the KAG parser. I might document this later. 108 | 109 | A third possibility is that the dialogue is written directly in `.ks` scripts, and can therefore use 110 | the KAG tags to achieve effects as usual. This was how things originally worked, but no recent or even 111 | semi-recent VN puts dialogue directly into `.ks` scripts. I'll write more about this at some point. 112 | 113 | Automatic word-wrapping implementations are usually tacked onto these scripts, if used. 114 | The original Japanese script files do not do automatic word-wrapping. 115 | 116 | # Plugins 117 | A major part of the KiriKiri engines' success is their extremely comprehensive support for plug-in DLLs. 118 | A massive number of plugins exist for the engine(s), and are used to implement anything from clipboard 119 | support to additional renderers, custom audio mixing and interactive catgirls. This is a sorely lacking 120 | list of some plugins by their filename, for which I've been able (and cared enough) to identify a source. 121 | - **[AlphaMovie.dll](http://kaede-software.com/krlm/plugin/alphamovie.zip)**: Free but not open source. Implements movie files which have an alpha channel. 122 | These files have the `.amv` extension. Encoder and playback via http://kaede-software.com/krlm/plugin/alphamovie.zip, 123 | Decoding/dumping via https://github.com/xmoeproject/AlphaMovieDecoder 124 | - **extNagano.dll**: Free but not open source. It is used to implement numerous layer transition effects. 125 | Used to be available at http://ymtkyk.sakura.ne.jp/krkr.STG/plugin/extNagano.html, but I haven't found a copy of the archive. 126 | - **extrans.dll** 127 | - **[getSample.dll](https://github.com/wtnbgo/getSample)**: Used for reading sample data from `WaveSoundBuffer`, usually for mouth movement. 128 | - **k2compat.dll** 129 | - **kagexopt.dll** 130 | - **[KAGParser.dll](https://github.com/krkrz/KAGParser/tree/master)**: This is the core parser module of **KAG3**. 131 | - **[KAGParserEx.dll](https://github.com/wtnbgo/KAGParserEx)**: This is the core parser module for **KAGEX3**. It replaces `KAGParser.dll` when using **KAGEX3**. 132 | - **krmovie.dll** 133 | - **[layerExDraw.dll](https://github.com/wtnbgo/layerExDraw)**: Implements support for drawing onto Layers with GDI+. 134 | - **lzfs.dll**: KiriKiri LZ4fs Plugin. No source found. 135 | - **[menu.dll](https://github.com/krkrz/menu)**: Implements `Window.menu` to enable Win32 window menu bars. 136 | - **PackinOne.dll** 137 | - **pkutil.dll**: Provides public key cryptography utilities, generally used to verify file signatures and/or product keys. 138 | - **psbfile.dll**: TLDW 139 | - **psd.dll**: Possibly https://github.com/wtnbgo/psdfile 140 | - **textrender.dll**: A native code replacement for the all-script `TextRender.tjs` from **KAGEX3**. Source unknown. 141 | - **[win32dialog.dll](https://github.com/wtnbgo/win32dialog)**: For displaying native Win32 dialog boxes. 142 | - **[win32ole.dll](https://github.com/wtnbgo/win32ole)**: Allows calling into Win32 OLE/ActiveX components. 143 | - **[windowEx.dll](https://github.com/wtnbgo/windowEx)**: Extends the TJS `Window` class with some events and multi-monitor stuff. 144 | Mostly used to implement window resizing with a fixed 16:9 aspect ratio. 145 | - **[wuopus.dll](https://github.com/krkrz/wuopus)**: Adds support for [Opus](https://opus-codec.org/) audio file playback. 146 | - **[wuvorbis.dll](https://github.com/krkrz/wuvorbis)**: Adds support for [Ogg/Vorbis](https://xiph.org/vorbis/) audio file playback. 147 | --------------------------------------------------------------------------------