A complete guide to unpack and repack Yu-Ris engine files

[MrPalloncini]

Introduction

I wanted to make this guide since i couldn't find some complete guide to mod any VN on yuris engine. The main reason is that i played euphoria and i wanted to mod it.

All the examples you are going to find are my years of reverse engineering and online documentation on euphoria (Mangagamer) version of yuris (v474).

How Yu-Ris engine works

Yuris is an interpreter that uses code C-like, is often used with ERIS, which is the VN interactive engine part of the interpreter.
The engine use its own file format called "YPF" for archives and "YBN" for scripts. The contents of the YPF file are usually assets since the archive can contain all kind of media, except videos.
The engine can be configured to use debug mode, as well as a log mode if activated.
Usually is used with some assets protection, using the ypf format, the algorithm should change with major version of the SDK. It also offer a XOR encryption protection for the scripts files.
The engine uses SHIFT-JIS text encoding, to be compatible with Windows versions since 98 to today. This of course causes some issues with the text since the OS will use ASCII standard to read it.

Unpacking YPF files

Unpacking YPF files is quite simple since is a standard Zlib compression, however tools may be incompatible depending on the engine version.
You can easily unpack those files by using yu-ris text replacer, arc_conv or GARbro.

GARbro has a really simple UI to use and can extract each archive by guessing the key or using a list of known keys for each game you want to unpack.

arc_conv is quite simple to use too, just double click the exe and pick the file, it should extract the ypf file into a folder in the same directory.

Yuris text replacer will extract the files automatically without any input from the user, this however might be incompatible with some later games, since the app is not developed anymore and the project is not opensource.

Unpacking Video files in YPF format

Video files aren't really compressed or encoded, so renaming the YPF file with an MPG extension will works. (Example: OP.ypf -> OP.mpg)

The encoding of the video itself is very specific and while it can be opened with a standard player, creating a new one for the game can be a pain, so i suggest to use sdk tools for repacking.

Unpacking YBN files

This is the part where all gets tricky, the game tries to protect all of the scripts assets with an XOR encryption. To find the text you must before unpack it from the YPF, usually is bn.ypf.
Then, you have to find the encryption key, which is only an XOR key, meaning that all the 0 in the file is a letter of the key. For This reason, you should pick up a file with most NULL chars in it, so you can find the key more easily.

As you can see, the file patter use so often x.0s chars, when the dot is an escape character so you must save the key in HEX format, in this case the key for euphoria is: 0x30731b78.

You can also use this site: https://wiremask.eu/tools/xor-cracker/ to crack the file with some analysis by uploading it.

Now that we have the key, we must find a good file to start our unpacking. I suggest to use an hex editor with a bitwise xor functionality with in, the only tool i found is Hex Editor Neo, but is a pay program, however there is a trial version, so if you can find a free one, let me know!

We can now import some files to start our cracking, i suggest to import some files in the middle that should contain text, in my case i used the file yst00140.ybn.

As you can see, we have some text that is used in the game itself, be aware that some file just use the text to instruct the engine and those files will be not exportable (yet).

Now that we just know the key and the file to unpack, we can use ExtYbn to extract the plain text on the file.

extybn is a ybn extractor, that can guess op-codes and extract the text with the given key, the app however must be compiled from Golang in a standard executable: https://github.com/regomne/chinesize/tree/master/yuris/extYbn

I will give you the precompiled application.

Now we should start the executable with the command line and use this argument: extYbn -e -ybn yst00140.ybn -output-opcode -key 0x30731b78

This will give us the op-codes, which are useful to extract the text without issues that we may have.

We now can unpack those files correctly using the following command: extYbn.exe -e -ybn yst00140.ybn -json unpacked.json -txt unpacked.txt -key 0x30731b78 -op-msg 95 op-call 29
the following commands are explained in the help file, but i will give you a summary.

• -e: puts the program in extract mode
• -ybn: choose the input ybn file
• -json: will create a json file with all the offsets (required for repacking)
• -txt: will create a txt file with all the text inside
• -key: will specify the key in hex format
• -op-msg/call: will specify the op codes to extract the text

We now should have the txt file, remember to use a compatible encoding (default one should be good) and use the syntax the engine will expect.

To repack the file, the command is almost identical with some key difference: extYbn.exe -p -ybn yst00140.ybn  -txt unpacked.txt -new-ybn modded.ybn -key 0x30731b78 -op-msg 95 op-call 29

in this case we removed the json file, which will be imported automatically, the -p mode to pack the file and the -new-bin command with the new filename.

You can also verify the file by manually decrypting in the hex editor like before. However yu-ris is quite sensitive with the text, so your new text may crash the game. Be sure to have repacked well with the right encoding and byte space.

Repack YPF files

To repack the archives, i suggest you to use the official sdk, you might need to get used to it, but i'ts quite simple and you can find the manuals in the official site, they are in japanese but you can use translate with that url.

The sdk should match the game version, however the only important thing is that the sdk must use the same repacking algorithm of the game. I'll leave the sdk for euphoria, but is possible to get it from the official site with an http request.

Inside the engine folder, you should find a subfolder called system, then the YsPac folder. Inside that folder, there is the YPF packer that we are going to use.

First we must drop the extracted folder inside the application and select it. Then we must click the top left menu bar, then click the second parameter. This will export the file.

That's it, the file should now be exported as a YPF file.

 

Feel free to contribute and improve this guide, if you have any issues let me know.

 

Yu-Ris SDK link: https://mega.nz/file/FQBgxJib#Yirgo01FPfDQu8Mte2b3dGMSxZx2UPyjIDDMhZZ2mU0

extYbn link: https://mega.nz/file/FQBgxJib#Yirgo01FPfDQu8Mte2b3dGMSxZx2UPyjIDDMhZZ2mU0

[Saiph]

Thank you so much for doing this guide!

I managed to unpack a YPF file but now I'm having trouble to repack it 

The thing is I'm a newbie in all this stuff, what means I don't know how to identify the game version or its repacking algorithm...

Because when I follow the steps this happens:

Spoiler

Btw the game is this.

[MrPalloncini]

20 hours ago, Saiph said:

Thank you so much for doing this guide!

I managed to unpack a YPF file but now I'm having trouble to repack it 

The thing is I'm a newbie in all this stuff, what means I don't know how to identify the game version or its repacking algorithm...

Because when I follow the steps this happens:

  Hide contents

Btw the game is this.

You might get this error message because you are trying to repack the file in a folder that use SHIFT-JIS standard name, i suggest you to repack the folder in the desktop and without using a locale emulator (if you are using one). I've been able to repack the file, but the game refuse to work because the key of the compression is different. The game you are trying to repack uses a custom version of the engine (i think), which should be 500 (even if the exe says it's 555, idk). Because i'm not a programmer, i can't say that well how the repacking works for those versions and the official SDK for this version is not available. I recommend you to check YPF Manager Tool to try it for yourself, but i couldn't repack it even with that tool. The reason why i use the official SDK is because it's the only decent repacker out there, since ypf repackers aren't common. If you are able to find the exact version and the key, GARbro might be able to repack it too, but i already tried it. I'll try to work on this, but i can't guarantee you that i'll be able to repack it. However by using YPF Manager tool the game doesn't give any error, it just doesn't display the images. If you have more details, let me know.

 

YPF Manager Tool precompiled: https://mega.nz/file/AN51FIbB#RBpPUPT4haxhTYAplxNPtt7SN7SKrDFGkdCZHcQaLBU

[Saiph]

4 hours ago, MrPalloncini said:

You might get this error message because you are trying to repack the file in a folder that use SHIFT-JIS standard name, i suggest you to repack the folder in the desktop and without using a locale emulator (if you are using one). I've been able to repack the file, but the game refuse to work because the key of the compression is different. The game you are trying to repack uses a custom version of the engine (i think), which should be 500 (even if the exe says it's 555, idk). Because i'm not a programmer, i can't say that well how the repacking works for those versions and the official SDK for this version is not available. I recommend you to check YPF Manager Tool to try it for yourself, but i couldn't repack it even with that tool. The reason why i use the official SDK is because it's the only decent repacker out there, since ypf repackers aren't common. If you are able to find the exact version and the key, GARbro might be able to repack it too, but i already tried it. I'll try to work on this, but i can't guarantee you that i'll be able to repack it. However by using YPF Manager tool the game doesn't give any error, it just doesn't display the images. If you have more details, let me know.

 

YPF Manager Tool precompiled: https://mega.nz/file/AN51FIbB#RBpPUPT4haxhTYAplxNPtt7SN7SKrDFGkdCZHcQaLBU

Oh! thank you so much for your quick response and for your help! 

The version of the engine is indeed 555, now the problem is idk how to find out the key ;-; as I told you, I'm so noob for this stuff xD

The thing is I'm trying to add MTL translations made with DeepL (they're pretty decent), so I successfully managed to unpack the scenario.ypf file with GARbro to edit the files, but the tough thing is repacking it 

Well, I actually managed to repack the file with YuRIS Tools by fengberd but:

• I can't open it on GARbro like the original one (this is a bad signal lmao)
• When trying to open the game it doesn't open and sometimes these windows appears

 

Anyways, thank you so much for your help ^^ I'll try it with the YPF Manager Tool~

[MrPalloncini]

17 hours ago, Saiph said:

Oh! thank you so much for your quick response and for your help! 

The version of the engine is indeed 555, now the problem is idk how to find out the key ;-; as I told you, I'm so noob for this stuff xD

The thing is I'm trying to add MTL translations made with DeepL (they're pretty decent), so I successfully managed to unpack the scenario.ypf file with GARbro to edit the files, but the tough thing is repacking it 

Well, I actually managed to repack the file with YuRIS Tools by fengberd but:

• I can't open it on GARbro like the original one (this is a bad signal lmao)
• When trying to open the game it doesn't open and sometimes these windows appears

 

Anyways, thank you so much for your help ^^ I'll try it with the YPF Manager Tool~

Ok, the errors you are getting, are related to the version of the YPF file, the engine detects that the compression is different or the key is invalid and therefore refuse to load saying that the assets are duplicated or tampered.

Now, i've been able to mod the YPF file. First i suggest you to extract the file using YPF Manager Tool, then you should get a folder with the name of the file, and a subfolder that will contain all the files (example, to should get: cgsys -> cgsys -> all the files), you then need to take note of the engine version (in this case looks like ver 500) an then repack the first folder with the engine version (example: YPFManager.exe -c cgsys -v 500). Keep in mind that this solution might be not perfect since the tool compress the data inside the file even when it shouldn't, so the engine might refuse to load assets.

[Saiph]

On 1/13/2022 at 12:54 PM, MrPalloncini said:

Ok, the errors you are getting, are related to the version of the YPF file, the engine detects that the compression is different or the key is invalid and therefore refuse to load saying that the assets are duplicated or tampered.

Now, i've been able to mod the YPF file. First i suggest you to extract the file using YPF Manager Tool, then you should get a folder with the name of the file, and a subfolder that will contain all the files (example, to should get: cgsys -> cgsys -> all the files), you then need to take note of the engine version (in this case looks like ver 500) an then repack the first folder with the engine version (example: YPFManager.exe -c cgsys -v 500). Keep in mind that this solution might be not perfect since the tool compress the data inside the file even when it shouldn't, so the engine might refuse to load assets.

I managed to repack it but just the first word appears xDD, the whole sentence is "It was a summer day when the cicadas were chirping annoyingly."

Spoiler

 

[MrPalloncini]

On 1/18/2022 at 9:47 PM, Saiph said:

I managed to repack it but just the first word appears xDD, the whole sentence is "It was a summer day when the cicadas were chirping annoyingly."

  Hide contents

 

Sorry for the late response, i checked the script and i think the problem is the space character, which the engine this is a termination line. Writing the phrase with a comma or other symbols displays the text correctly. I'll do more research to find out how to bypass this issue but i don't know if i'll be able to. The problem is that without any script in the engine itself, this might not be an easy fix. And since i'm not a programmer i can't debug the engine to know exactly how to patch this issue. If you find a workaround, let me know.

 

EDIT: With the help of my friend i've been able to find out that the engine support space and some special characters in the name field. The script however doesn't support characters that are not expected, like spaces and special chars. The workaround for now is to use the space that you can find in the script itself, which is a NULL character (00 in hex). For the special chars however you should still use the chars provided with the font the engine wants. I don't know if the engine use special fonts or defined scripts to prevent special chars. Yu-ris however support a gaiji mode (that was used in euphoria), which can replace special defined chars with a custom font, but I don't know how to insert that however.

Edited January 27, 2022 by MrPalloncini

[Sisulizer]

@Saiph @MrPalloncini why don't you guy repack to update1.ypf, update2.ypf, etc. It should work if you remain like this update1>[folder name(E.g:ysbin, cgsys)]>all the files. And this to find Yu-ris's key(you need something to inject into the game's exe like cheat engine)

 

Edited February 23, 2022 by Sisulizer
add

[Sisulizer]

and this tool to extract all script files at once, do not need key or anything, can add auto word-wrapping. 

For some clock-up vns, text will be like this 

To fix it Idk how, but I saw company do something like this. They manage to do it somehow, anyone has any ideas?

 

[Sisulizer]

Found it, but the problem is how to xor the .ybn file contains font

[MrPalloncini]

Thank you so much for those software you suggested, for xor the file itself, i just use hex editor neo with the bitwise xor function and the hex keys. Are you trying to add the font in the game or those files were already there?

[Sisulizer]

On 2/27/2022 at 3:58 AM, MrPalloncini said:

Thank you so much for those software you suggested, for xor the file itself, i just use hex editor neo with the bitwise xor function and the hex keys. Are you trying to add the font in the game or those files were already there?

I'm trying to but Idk how, you need to add those files yourself

Edited February 28, 2022 by Sisulizer

[Sisulizer]

Here is a sample font file of Euphoria(Eng)

[MrPalloncini]

Sorry for my very late response, but i had some personal troubles and i couldn't work on it too much. But i found something interesting. Looks like that the engine keep the order of the single script file in the name of the file itself, so when the engine looks for yst_list.ybn the 11th file inside that is es_font, which is the file you have found. The es_font is standard in the engine and is always loaded, therefore you might be able to mod the file itself and insert the custom font inside cgsys. I however do not know how to do that, since i couldn't work too much on it and i don't know ho to handle the NULL chars inside the file, since around i couln't find any tool for editing the script itself other than translation and missing any format that yuris ask, will trigger an error in the engine.

I'll try my best to find out how to handle that, but i don't know if i will be able to.

[Ryu11]

The repacking app - YsPac - doesn't work well  It only repacks images, sounds files, but doesn't repack other files. 

After a lots time google it, I found a wonderful application. It does a good job for both unpack & repack ypf files

https://arca.live/b/handtranslator/37085669?category=툴&target=all&keyword=&p=1

 

[HataVNI]

Holy shit, you are a hero. I did not know that this forum had new posts about such important stuff this recently.

[MrPalloncini]

On 8/6/2022 at 12:37 PM, Ryu11 said:

The repacking app - YsPac - doesn't work well  It only repacks images, sounds files, but doesn't repack other files. 

After a lots time google it, I found a wonderful application. It does a good job for both unpack & repack ypf files

https://arca.live/b/handtranslator/37085669?category=툴&target=all&keyword=&p=1

 

Thank you very much for this powerful tool, i'm goung to try this when i have more free time

 

On 8/9/2022 at 3:54 PM, HataVNI said:

Holy shit, you are a hero. I did not know that this forum had new posts about such important stuff this recently.

This took me 4 years of reversing engineering starting from scratch, since i'm not a programmer it was difficilt for me to learn all of this stuff. Also, i don't think i can post more information since i have few problems in my personal life. I hope i can continue on  this project. Thank you all so much for your support

[wasd123333]

Hello, have you tried bypassing the decryption part by going through translator++?

Is there an easier way to go through the decryption part? No idea what you mean by hexcodes and XOR and stuff. I am able to extract and gather the .ybn files, but I can't get the game to run when I repack it.

[ArianKar98k]

i know it's a lot to ask but, can you make a video explaining how to do it? like, i don't understand very well what i have to do and i only need to do this one time in my entire life, and the UI is full of strange characters and not a single readable word.

[alina996]

On 2/23/2022 at 12:42 PM, Sisulizer said:

@Saiph @MrPalloncini why don't you guy repack to update1.ypf, update2.ypf, etc. It should work if you remain like this update1>[folder name(E.g:ysbin, cgsys)]>all the files. And this to find Yu-ris's key(you need something to inject into the game's exe like cheat engine)

 

Thinks your good idea. I finally can use a uncen game's cg to replace the origin game. Just extract the uncen game's cg file(e.g: cg.ypf) and the origin game's. Replace the origin game's cg and then repack as 'update1.ypf'(I use ypf manager tool).Finally, delete 'cg.ypf'.

it don't need the pack key, and it work well.

[kiraio]

Thanks, man. I haven't encountered any VN with YU-Ris engine though, but I certain this guide will be useful in the future.

[MrPalloncini]

Hi everyone, sorry for the fact that i was absent all those moths, but thing IRL became a bit hard for me since my mother passed away few month ago.

I will now try to answer few things.

On 3/19/2023 at 10:01 AM, wasd123333 said:

Hello, have you tried bypassing the decryption part by going through translator++?

Is there an easier way to go through the decryption part? No idea what you mean by hexcodes and XOR and stuff. I am able to extract and gather the .ybn files, but I can't get the game to run when I repack it.

AFAIK translator++ is mainly developed for RPG Maker games and doesn't natively support yu-ris. The best current method for translating is using YurisTool and repacking the files.

 

On 4/3/2023 at 9:02 AM, ArianKar98k said:

i know it's a lot to ask but, can you make a video explaining how to do it? like, i don't understand very well what i have to do and i only need to do this one time in my entire life, and the UI is full of strange characters and not a single readable word.

I don't have a way to make a video rn, but if you just need to extract the text in readable format, you can use GarBro which decode automatically every text file or you can use YurisTool. Might me a bit hard but if you keep at it you will learn how to do this, i started from 0 too.

 

On 6/6/2023 at 11:09 PM, alina996 said:

Thinks your good idea. I finally can use a uncen game's cg to replace the origin game. Just extract the uncen game's cg file(e.g: cg.ypf) and the origin game's. Replace the origin game's cg and then repack as 'update1.ypf'(I use ypf manager tool).Finally, delete 'cg.ypf'.

it don't need the pack key, and it work well.

As long as you don't want to edit the .ybn files you don't need a key to repack the .ypf, you just need to know the version of the SDK since the algorithm changes between each version.

 

On 6/15/2023 at 1:55 PM, kiraio said:

Thanks, man. I haven't encountered any VN with YU-Ris engine though, but I certain this guide will be useful in the future.

Regarding VNs that uses yuris there aren't that many, the most famous is ozmafia and all clockup games that uses the engine. Also cluckup uses a modified version of the engine since the developer works there.

I'm sorry for my absence and i won't be present in this forum too much in those month too, i'll try to stick around as much as i can if anyone needs help or have questions. Thank you

Edited September 9, 2023 by MrPalloncini

[Trail_Wind10]

Sorry, call me dumb but I just can't understand the unpacking ybn files. So I get that we have to find the XOR key but I don't know where or how to find that. I used the XOR Cracker but I didn't get the key that I wanted. Could you like where to find the XOR Key? I'm just confused on how to find this

[mennin123]

holy shit this looks insanely difficult and tiresome just to get the text lol

nice post btw

[Ageko]

i managed to unpack and repack but how to use yuris tool to translate? Can you elaborate on this?

 

Edited December 23, 2023 by Ageko
misspelling