Dev - Other maker Kero Blaster / Pink Hour hacking and editing. (Read 871 times)

  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
hello! I have played a lot of Kero Blaster (from the creator of cave story) and you should probably buy it and play it : http://www.playism-games.com/games/keroblaster/
 
It's really good
 
but what's also great is that I've been diving into the scripting and level data.
 
Pink Hour is a free side-game to Kero Blaster (http://www.playism-games.com/games/pinkhour/) and it uses the same engine (and as such same level and scripting etc etc) which means I've got more stuff to play with AND you don't gotta buy Kero Blaster to start hacking away. which is super cool
 
INTERESTING STUFF
 
First I'll start with the files: (i'm using Pink Hour to show all this stuff, same stuff is in Kero Blaster mostly)

 
you've got 8 folders in here, here's a quick rundown on what's inside each one:
 
assist - Some weird stuff! I'm yet to understand most of it but I am pretty sure that this is all stuff that Pixel's level editor uses. A closer look at the files inside:
 
attribute.png - looks like debug tiles for all the types of collision. not sure what everything is yet, but you can see slopes and damaging tiles for sure.
 
default.pxeve - this is a template level script, i'll go into the scripting language more in a bit.
 
flags.txt - i'm pretty sure that this is just a reference file, for data that is used maybe in the level data files? this will no doubt come in handy when i dive further in.
 
scroll.txt - haha I dunno, something to do with scrolling of course but mhm probably not important
 
unittype.png - pretty much definitely the "entity palette" for use in the level editor
 
unittype.txt - a handy list of what all the entities are. definitely will come in handy.
 
bgm - surprisingly the music data. all the music is .ptcop format, which is the music format that PXTone exports (http://www.cavestory.org/pixels-works/pxtone-collage.php), a music tool created by the developer of this game.
 
field - level data! this is interesting stuff!! but!! its not plain text unfortunately. I'll go into what i've found in level data further on.
 
img - most of the graphical data! editing this stuff is super easy. (just make sure you keep it indexed! i haven't checked yet but i'm pretty sure it doesn't support full colour pngs, i'll update this when i bother checking haha)
 
localize - translations are stored here, some graphical pieces are also in here.
 
profile - save data, yeah?
 
se - sound effects! in .ptnoise format which iirc can also be created with one of Pixel's tools.
 
text - scripting data!! even more interesting! all the scripts are in plain text, so you can very easily start editing things :) I'll go into the scripting stuff now
 
 
--+SCRIPTING IN KERO BLASTER AND PINK HOUR+--
 

 
Scripting takes a really simple format, and if you've done a little coding it shouldn't be too difficult to pick up.
 
You've got 3 types of code, Labels and 2 kinds of Functions.
 
Labels are lines that you can jump to, with some special labels being called by Entities or through some other method. The first of these special labels is:
 
*[IN]
 
which you can see at the start of every script file. the functions after this label are called when the player has entered the map!
 
Functions are all preceded with a "<" and are 4 characters long. Functions that a followed by square brackets (like "<muLd[kb_shop_a]" you can see above) are taking an argument (sometimes more than one)
 
You can put functions on more than one line, as far as I've seen linebreaks don't do anything. Here's a list of just a few useful functions and my rough knowledge of what they do:
 

 

//script delay. i think it's in frames.
<dely[time]  


//another delay script, but locked to 60 
<dl60


//jumps to a Label, often used to go to a new level, but i'm not exactly sure how it knows this.
<jump[Label] 


//opposite of <fadI, fades out. 
<fadO


//Loads a music file from the bgm folder. argument is any filename, minus the .ptcop extension.
<muLd[.ptcop file] 


//Plays the loaded music.
<muLp 


//Stops the music, if any playing.
<muSt 


//I believe this fades the music in. (though it may fade the screen. I haven't checked properly!)
<fadI 


//ends a block of code. nothing after this command will be executed (i think!! so much i need to double check!!)
<exit

//goes to the home/title screen. in Kero Blaster this is the Load Game screen.
<home 

 
 

 
I'll update this more when i find more stuff (i know more scripts but I need to write them up)
 
--+LEVEL DATA IN KERO BLASTER AND PINK HOUR+--
 
I am still super[/b] sketchy on how this works exactly so I'm gonna have to do more work before I can do a proper write-up! sorry! Here are some screens to show that I am working on it though!



Last Edit: May 14, 2014, 10:33:57 am by JMickle
www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
new scripts:



 

//script delay. i think it's in frames.
<dely[time]  


//another delay script, but locked to 60 
<dl60


//jumps to a Label, often used to go to a new level, but i'm not exactly sure how it knows this.
<jump[Label] 


//opposite of <fadI, fades out. 
<fadO

 
Last Edit: May 14, 2014, 10:27:18 am by JMickle
www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
As far as level loading goes, tiles are stored sequentially with one byte per tile. the tiles are loaded from tilesets defined near the start of the file.
 

the title level from Pink Hour opened in Notepad++
 
You've got a header at the start, then a little further on you have some bits of plain text we can use without even byte editing:
 
00title is the script file that the level uses. change this to another one to...  break the game i guess haha
00PHerabu, 02PHstart. I'll be honest, I'm not sure why these are here. They are definitely references to other levels, though.
fuGB11. this graphic has all the enemy sprites from Pink Hour in. I'm guess it's used to load in the graphic to memory so the entities can use it.
mptOfficePH0, mptPBOffice1, mptClinicBack1 these are tilesets that the level uses! change this for some fun glitchy times!
pxMAP01 these are identifiers for where the tile data is stored. after each one is a non-fixed list of byte that translate to 1 byte per tile.
 
if you look at the tileset mptPBOffice1:

 
each tile is 8x8 pixels, and the index of each one can be counted starting at 0. so the first row of tiles is 0 to 15, the next row is 16 - 31 etc.
the bytes do not translate directly, they are offset by 240 iirc, so to translate add 240 to each byte read, and that should refer to the correct index on the tileset.
 
This is as far as I got! I think a foreground and background layer is stored, and i'm not sure where entity positions are stored yet, but I'm working on it! As you can see from my screenshots in the OP, I didn't successfully manage to get the foreground tiles from the first screen of level one, but this method managed to get the background layer.
www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
making some progress decyphering the header of the map files 

www.jmickle.com
  • Avatar of denzquix
  • PipPipPipPipPip
  • Group: Member
  • Joined: Aug 22, 2012
  • Posts: 630
this is really cool stuff, good luck with working it all out!
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
Thanks!
 
This level loading is some real bullshit, honestly. I've basically got them loading properly, with a load of metadata and everything, but they come out looking like this:

 
The backgrounds look fine, and they are shorter than the levels because of parallax scrolling, but those foreground tiles are obviously completely wrong. They work absolutely fine on this level though:
 

 
this is tedioussssssssssssssss
 
I'm happy that I've at least got this far. I am definitely missing something, though, and I'd love to know what it is.
www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922

 
i fucking did it
 
i'm so happy
www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
Still need to grab entity data and figure out what some of the data i'm ignoring means, then I'll write a quick guide to how the level data is formatted.
www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
HOLY CRAP - I MADE A LEVEL VIEWER TOOL
 

and you can get it right here >> https://dl.dropboxusercontent.com/u/8943931/games/2014/KeroHackToolsv1.air <<
 
INSTRUCTION FOR USE (because i have worked zero on usability so far)
 
Install the app anywhere it doesn't really matter.
 
When you open the app, you need to find the rsc_k folder for kero blaster or the rsc_p folder for pink hour. When you find it, select it and hit select folder
 
Once you have done that, hit that pink load level button and select from the list of many levels in the game(s)
 
THIS IS BARE BONES
 
all you can do so far is look at the tiles for any level, you can't even pan around the levels yet. ALL IN GOOD TIME i am tired and need to sleep :)
 
I hope you enjoy! If you have any questions/comments tweet me at @jmickle_ or drop me an email here: jmickle a t goatpox.net
www.jmickle.com
  • Avatar of Ice Baby1
  • Power to the parsley
  • PipPipPipPipPip
  • Group: Member
  • Joined: Oct 31, 2012
  • Posts: 637
criminy !!! very impressive work!!! this sort of reverse engineering is always fascinating so please keep it up
  • Group: Member
  • Joined: Sep 9, 2013
  • Posts: 20
I'm loving what you're doing here jerry. I've been trying to mess around with it after reading all this and sadly I'm not doing too hot lol
 
So I've just been messing with the art assets.
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
thanks everyone! as I said I want to do a writeup of the file format when I understand it a bit better so that other people won't have to do all the tedious work I just did :) First things first though I need to make this app nicer to use and get started on seeing if I can get it to edit levels.
www.jmickle.com
  • Group: Member
  • Joined: Sep 9, 2013
  • Posts: 20
You've probably already got this figured out but I know what the 00PHerabu, 02PHstart is in that files. It looks like the first one is the level before it and the second is the level afterwards. I'm restricted to just using Pink Hour so I'm not sure if it's exactly the same for Kero Blaster.
 
This is 01PHmizuE
 
PXPACK121127a** ƒsƒ“ƒN‚Ì–`Œ¯@’†‚Ù‚ÇE01PHmoguraE
01PHoyoguE02PHmizu fuGB11       mptGB11 mptPHback   pxMAP01 [   22 2 2 2 22“”…2   2 2222“”ƒ„2  2 22“”             2 †…               22 2†ƒ„22 22 22†122 2 2222            3                22“”ƒ„                      22           222                       2†                    22                                                                  222                                                                                                                                                                                                                      R                                                                                     RR RS²³²³                                     R R                               R R RRRR bcs¡¢¡Ã                                    –ss`a                         R bcs‘’‘³000000000000000000000000000000000000{{{{{{‘³            RRR    RRbcs¡¢¡¢ÈPPP@@P@@@@P@P@P@P@@PPPPP@PP@PP@P@PÊÉ×ÉÉ×É¡¢RR   RR    ‘’‘³ØPÙPÙ@ÙÙPÙ@Ù@@Ù@@Ù@ÙPPÙPÙÙPPÙPÙÙPPPÚ×ÉÉÉÉב’‚²³¡¢¡¢É‹×‹×‹×É‹É‹É‹‹É‹‹É‹×‹‹É‹×É‹‹×‹×׋‹‹ÉÉÉ×ÉÉÉ¡¢¡¢‘³ÉÉÉÉ×ÉÉÉ×××ÉÉÉÉÉ×É×ÉÉÉ×ÉÉÉ×É×ÉÉÉÉÉÉÉÉ×ÉÉÉב’‘’‘’pxMAP01 [                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          pxMAP01       Z      Y                  ƒ  
    ƒ      XR     Ž  
    Ž       6      @      4      =            
   PBmizu G      ,     ˆ :     ˆ '           t 2
    t =
    t C
     "     t )
    t 4
    t 8
    t J    
The level that comes before it is 01PHmoguraE and the level after is 01PHoyoguE. I can't say this is 100% correct but it looks like that the filename for the levels follow this pattern
 
01 - In Pink Hour if is for difficulty it seems. All levels with 02 are the hard kind
PH - At first I thought this stood for Pink Hour, but without seeing the Kero Blaster files I'm not sure.
mizu - I thought this was cute. Each level (with the excepts of start, boss, last, and goal) are named by a Japanese word that describes it
*E - This only shows up in the easy level files. Just another sign of it not being with the hard levels which do no sport the Es.
 
The level order for Pink Hour (Easy) goes
  • Start
  • Mogura(Mole)
  • Mizu(Water)
  • Oyogu(To Swim)
  • Tiaya(Tire)
  • Boss
  • Naraku(Hell)
  • Last
In the flags.txt it lists this area as "Normal". I'm just calling it Easy because of the E on the ends.
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
there are up to 4 level names in every level file, and while they maybe used for before/after, it doesn't explain it enough for most of the levels. I still gotta figure out what it is for. (some levels reference /very/ different levels, which is confusing)
 
The level name format is such: 00 is for before-game stuff, and 01 upwards is used for chapters in Kero Blaster. It's purely a naming convention and probably just used to separate the two difficulty modes in Pink Hour.
 
after each word pxMAP01 are two short ints that describe the size of the level (so in the tutorial map for Kero Blaster it is 31 then 15 (or in solo bytes: 0, 31, 0, 15), then two blank bytes, and after that the data for all the tiles
 
the tile data is stored in bytes, where one byte is a reference to a tile on the tilesheet, using a format like this:

 
These tiles are placed in rows, so for example if the data looks like this:
pxMAP01 08 08 00 33 33 33 33 33 32 33 33 33 33 33 33 33 48 49 33 33 33 33 33 33 33 32 33 33 33 33 33 33 33 48 49 33 33 33 33 33 33 33 33 33 33 96 97 98 33 33 33 33 33 112 113 114 33 33 33 33 33 112 113 114 33 33 33

disclaimer: the data does NOT look like this, this would actually look a little more like this (using one byte per character): pxMAP01␈␈␀!!!!! !!!!!!!01!!!!!!! !!!!!!!01!!!!!!!!!!`ab!!!!!pqr!!!!!pqr!!!
 
we can see that the map has a width and height of 8, so now we can reorganize the data to look like this:
 33  33  33  33  33  32  33  33 
 33  33  33  33  33  48  49  33 
 33  33  33  33  33  33  32  33
 33  33  33  33  33  33  48  49
 33  33  33  33  33  33  33  33
 33  33  96  97  98  33  33  33
 33  33 112 113 114  33  33  33
 33  33 112 113 114  33  33  33

 
and by referencing the tileset as we did above, we get a level looking something like this!

www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922

 
Current state of KeroHack, redone some UI and those numbers across the top show which tile layers are active, and you can press 1 2 or 3 to make it visible/invisible. I have a feeling I was mistaking the purpose of one of them, which means I may be able to show levels a bit better soon. Also just adding in the ability to drag the levels around, maybe zoom as well?
www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
Tile editing is getting very close to working, just a couple things to iron out (I hope).

https://vine.co/v/MX99Z39YieX
http://instagram.com/p/oGhjAoIU40/
www.jmickle.com
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
I did it! :D you can now load, edit AND save levels :D :D :D
 
but WATCH OUT there are probably still some huge bugs :X if you find any feel free to tweet me at @jmickle_ or drop me an email here: jmickle a t goatpox.net and i'll try and fix them asap
 
the one command i forgot to include instructions for: hold space to bring up the tile palette!!
click a tile on it then click on the level to place it! also: press tab to switch layers (will probably break something haha)
 

 
get it here!!
>> https://dl.dropboxusercontent.com/u/8943931/games/2014/KeroHackToolsv1_1.air <<<
Last Edit: May 17, 2014, 06:03:58 pm by JMickle
www.jmickle.com
  • Group: Member
  • Joined: May 17, 2014
  • Posts: 2
After the tile in data in 09PBstart.pxpack the first 16 bytes relate somehow to going to the next level. the first byte describes the size (I'm pretty sure) 
Comes entity data
EDIT: The the first  byte is the amount of entites. I don't know about the second byte yet. 
(FLAG BYTE) (ENTITY TYPE BYTE) (2 BYTE SHORT INT X POS) (2 BYTE SHORT IN Y POS) (then four blank bytes 3 flag bytes and one byte that can a lenght of a string)
MORE EDIT: Also I'm not super sure about the 2 byte short int. it might just be a char. When I change the first byte of x it stays in the same place, but with y it disappears.
 
after that comes (in hex)
00 0D 00 00 00 00 01 96 00 22 00 0C 00 00 00 00
01 96 00 2C 00 07 00 00 00 00 11 96 00 5D 00 0B
00 00 00 00 01 01 00 07 00 06 00 00 00
and then afterwards the lenghth of a string and a string that says PosStart
whenever you see 96 its talking about the bat.
 
 
Some entities used in the start level  (in hex)
96 bat
48 barrier // Its there in the file, but I don't see it in the map
12 that snail thing
74 green plant
 
1D when you go past this point it makes you go to the next level
 
the first 1A with 00 after it  is where you return if you go back from the next level
 
01 with the string PosStart is where you start when you enter the level the first time
 
the second 1A with 01 after is where you go to when you die in the level
 
the last entity is a barrier (48) at 0E 01 which I never see in the level, but it's there I guess...
 
All entites with Hex code included
Just taken from the unitype.txt file and numbered
 
the 01 96 00 22 00 0C describes the first bat
01 might be the flags asociated with the entity. 01 means facing left, 11 means right
after that comes the position, x than y. so the first bat is facing left and is at 22, 0C.
That's all I got for the entities so far. Hope it helps.
 
 
@TehSquidz0rz
Last Edit: May 19, 2014, 08:20:34 am by instasquid
  • Avatar of JMickle
  • I gots a lego!
  • PipPipPipPipPipPipPip
  • Group: Premium Member
  • Joined: Feb 4, 2007
  • Posts: 1922
Ah, excellent! I made some progress with entity data with help from this post (again, thank you!!) so I'm gonna try and have an entity editor in the program tonight :)
 
the unittype.png and unittype.txt in assist have been super handy, too.
www.jmickle.com
  • Group: Member
  • Joined: May 17, 2014
  • Posts: 2
Awesome, i'll have to load my pc and try it! If someone can figure out the beginning header part a bit more, and figure out the scripting then we can make everything in the level!
I was looking at the entity data for taiya and it uses the string at the end  of an entity to name the entity to reference in the script, and it uses lots of weird flags on the entities. I have yet to figure out how that all works together though, it seems pretty complicated.