43 users online: Abstract, Akaginite, Alexander Barnes,  Ayami, Bonobi, danielgames8899ui,  DeppySlide, edgar,  Fyre150, Golden Yoshi, Green, Guleyan112, h.carrell, Hammerer, iota, katun24,  Kevin, King Mayro, lo fang 123, Maw, MirrorReflect, MrDeePay, NerDose, Nitrogen, Phyll, Ringo, Ron Mexico, Sammmoo,  Sayuri, sholmes, simon.caio, sio-kedelic, SomeGuy07, Th3Ruan057, The_Uber_Camper, TheMorganah, TheXander, trillian, Tulip Time Scholarship Games, will___, wye, yoshi3706, Yutuz - Guests: 199 - Bots: 175
Users: 64,316 (2,438 active)
Latest user: Svety7

Lunar Helper: Updates and plans

Super Mario WorldTool

  • Pages:
  • 1
  • 2
Time for the biannual update about new Lunar Helper features, I guess!

Huh, wait what is Lunar Helper?
If you're not familiar yet, Lunar Helper is a build system for SMW ROMs which lets you rebuild your ROM from scratch and quickly apply any tools with the press of a single button. It also combines very well with version control tools such as git if you're into that sort of stuff (like me). This makes it much easier and more reliable to "remove" patches from your ROM and should make "porting" your ROM completely unnecessary, along with various other benefits when using git.

Oh, I see, where can I get it?
Here are some links:
- GitHub release for Lunar Helper v4.0.3
- GitHub repository (if you're interested in the source code)
- Pending Lunar Helper update to v4.0.3 in the tools section
- My project template which comes with Lunar Helper v4.0.3 and is easy to set up
- The Romhack Races baserom which comes with Lunar Helper v4.0.1

And here are the previous C3 threads about this tool:
- Winter 2022
- Summer 2022 (this one has a slightly outdated video, if you're curious)

What's new?
As usual, a lot has changed since half a year ago and Lunar Helper comes with some major new features.

The wiki
The most important new "feature" is probably an extensive wiki I have been working on which covers just about everything there is to know about Lunar Helper and Lunar Monitor in detail. You can find it here. I have decided to include instructions for setting up a new project as well as moving an existing project to the workflow since people have asked me about this on several occasions, so I hope this is a useful resource. For more details on any of the following features, please check the wiki, I'm just giving a short summary here!

Customizable build order
The order of resource and tool insertion can now be customized as needed for your project. It turns out that there likely isn't a universal order of insertion that works well for all resources, so this should ensure that any resource which expects certain other resources to be inserted before/after it can be used with the tool. Changing the build order is straightforward, this is what the default one looks like:
    Graphics                -- Insert standard GFX
    ExGraphics              -- Insert ExGFX
    Map16                   -- Insert Map16

--  TitleMoves              -- Uncomment this if you're inserting title moves

    SharedPalettes          -- Insert Shared Palettes 
    GlobalData              -- Insert Overworld, Title Screen and Credits 

--  Patches                 -- Insert all remaining patches from the patches list that 
                            -- are not explicitly mentioned in this build order

--  PIXI                    -- Insert custom sprites
    Levels                  -- Insert all levels

--  PIXI                    -- Uncomment this if you're using Lunar Magic 3.31 or higher

--  AddMusicK               -- Insert custom music
--  GPS                     -- Insert custom blocks
--  UberASM                 -- Insert UberASM code

--  Patches/some_patch.asm  -- Example of inserting a specific patch at a different time

Any lines can be moved up/down and commented/uncommented to customize the order.

Safety first
It used to be the case that you could accidentally overwrite the contents of your ROM without them having been exported first when using the tools incorrectly, which could lose you a lot of progress. This has been remedied, Lunar Helper can now detect that there are unexported resources in your ROM and will ask you if you would like to export them before building your ROM.

Build profiles
It often happens that we would like our hack to behave a little differently in certain situations, maybe we are debugging something and would like to have a nice in-game debugging UI that we have to insert as a patch or maybe we would like to have a test level teleporter while working on the hack, which we obviously would not want to be in the final release. For this purpose, Lunar Helper now allows users to have multiple "profiles" for one hack, which are essentially just different configurations that you can switch between quickly from inside Lunar Helper. For example, my project template comes with two profiles, a Release and Debug profile:

But you can do much more than just switch out configuration files using profiles, you can even customize code on the assembly level if you're into that kind of thing by writing code similar to this:
incsrc "../../.lunar_helper/current_profile.asm"

; other code here...

if defined("LH_PROFILE_Debug")
    ; do debug things here
elseif defined("LH_PROFILE_Release")
    ; do release things here

Automatic emulator determination
You used to have to explicitly specify the path to your emulator when trying to use the "R - Run" function of Lunar Helper to run your ROM from within its menu. This is now no longer the case if you already have your emulator set up in Lunar Magic. Lunar Helper can now figure out what the emulator you're using in Lunar Magic is and will attempt to use that one if you have not explicitly specified a different emulator in your config files, which is much more convenient.

Easier setup process
Lunar Helper will now offer to export vanilla graphics, map16, global data, etc. for you if the corresponding files are not found during a build, which should make the setup process much more streamlined both when creating new projects and moving old ones.

No lag Lunar Monitor exports
Lunar Monitor is a tool bundled with Lunar Helper that exports stuff when you save it in Lunar Magic to streamline the build process. If you've used previous versions of Lunar Monitor, you may have noticed some lag when it did this, because it would pause Lunar Magic while it exported the resources, this was especially noticeable when saving levels or map16. This should now be remedied and saves should feel as snappy as they would without having Lunar Monitor running at all!

New "O - Open project in File Explorer" function
This is just a nice little new menu entry in Lunar Helper which will open the root of your project in the file explorer for you.

Asar included
Asar now comes included with Lunar Helper, so there is no need to set it up manually anymore and insertion speeds for patches may also be slightly improved.

What the fuck is a globule? Good question.
If you are familiar with PIXI and GPS routines or UberASM library files, they're similar to those, except they can be used and shared by all tools across your entire project and be called from anywhere. They can contain anything you want, including data or code, are inserted by Lunar Helper directly and can even depend on each other if needed.

Here is a contrived example, if we wanted to be able to make Mario big from anywhere just by calling a globule, we could create a "MakeBig.asm" globule like this:
    LDA #$01
    STA $19   ; store $01 to powerup status, making Mario big!

Lunar Helper will make any label in a globule available in a file it generates, which can then be included by other code to call the globule, here is an example which we could use in, for example, an UberASM file, but also in a patch, sprite, block, etc.:
incsrc "../../.lunar_helper/globules/MakeBig.asm"`

    LDA $14
    AND #$07  ; every 8th frame...
    BNE .skip
    %call_globule(MakeBig_main)  ; make player big

The "call_globule" macro is automatically included when importing any globule for convenience and just ensures that the databank register is set correctly. Every label is available both as an actual label and also a define, so %call_globule(!MakeBig_main) would also be valid.

The command line
Lunar Helper now offers functionality for calling various functions directly instead of going through its menu. "LunarHelper.exe --build", "LunarHelper.exe --quickbuild" and "LunarHelper.exe --package" are all valid ways to call the program and will perform the corresponding action. This means you could even further automate building via scripts or git hooks if desired.

But what about Lunar Magic dialogs?
Great question, astute reader! Of course, it used to be the case that when Lunar Magic encountered an error during a Lunar Helper build, it would throw up a dialog box, which would halt the build process until the box was dismissed by clicking it, since Lunar Magic isn't really built as a command line tool. Luckily, I found a workaround and have managed to make Lunar Magic behave as if it were a command line tool during Lunar Helper's build process.

Previously, you may have encountered warnings such as this one:

These will now be turned into actual text instead via a mysterious and elusive process that I will not further detail:

In addition, when running for example "LunarHelper.exe --build", any of these prompts will be dismissed and the build will fail. This is to ensure that when a script executes this command, it is guaranteed to not "get stuck" indefinitely because Lunar Magic decided to throw up a message box that needs to be clicked.

Neat, what's next
I've been considering writing a sort of successor to Lunar Helper, as the code has become somewhat disorganized over time and there are some features and changes I have in mind which would require some drastic changes anyway, so look forward to a hopefully even faster and better tool in the future (if I have literally any time at any point, which may or may not happen!).

Happy C3 everyone :​)
I absolutely LOVE Lunar Helper, thank you for continuing to update it. Absolute must have.
To me, Lunar Helper is one of the greatest QoL updates our community has ever received, and it makes me very, very excited that not only are you continuing to update and maintain it, but that the software keeps finding new ways to make the build process smoother.

Thank you so much, underway!
I'm not a doctor.

Lunar helper is the best, I use it all the time. Great job on the wiki!
Scripting is absolutely essential to hacking the SMW, as is always building your ROM from scratch.
Your tools are a nice way to introduce these best practices to more people. Very nice!
Oh wow, this is an amazing tool! I should download it myself if I ever feel truly motivated to make a full-fledged SMW hack someday! My motivation has fell to shit, but maybe I'll find it in the future.
Just so you know, I'm very active on the site anymore like I was before; I'm mainly on Discord now.
the LM companion tool of all time. happy to see it maintained still. thanks underway!
I'm in support for the build ordering because one of the cases I had to deal with on 1.0.9 was when AddmusicK was used first, then UberASM. On 1.0.8, you merely had a series of NOPs when accidentally overwriting a branch in this fashion, but I accidentally caused the thing to crash when I upgraded the handling of Yoshi Drums to disable when Mario is not on Yoshi in more cases, which resulted in me adding a hijack and overwriting a NOP section... so I had to relocate the BRA opcodes in order to ensure that the build ordering would not matter in this case.

I may not use the tool myself because of a platform incompatibility, but you're essentially specifying some sort of a makefile in this fashion. Thus, at the absolute least, I'll be on an indirect lookout in case I hear something go wrong involving AddmusicK.
Originally posted by KungFuFurby
I may not use the tool myself because of a platform incompatibility, but you're essentially specifying some sort of a makefile in this fashion. Thus, at the absolute least, I'll be on an indirect lookout in case I hear something go wrong involving AddmusicK.

This is actually something I'd like to address with a successor tool as well, would love to support at least linux since I know there are plenty of people using it these days. Still brainstorming how to do it exactly since I'm not familiar with the "standard" setup on linux. If anyone has any experience with how I might best support this, please feel free to get in touch if you've got the time.
Somehow this entire thing flew under my radar; I screw up often enough where this would actually be a pretty decent time saver. Thanks a ton for putting the work into this!

Other Submissions of mine!
Unfortunately I am unintelligent and most of this thread read as jargon to me. But many people seem to be very excited and so I can join in the excitement as well! What you've done is great, and I am happy for you.

Many people are going to use this. #smw{:TUP:}
ask me if i give a f*ck...
Here's a suggestion.

When you are doing a long time hack, for example since 2017, and you are doing the hack until 2023, but you want to update the Tools to not have problems, like PIXI, UberASM Tool, etc.
Would it be possible?

Wow, there’s a lot going on with this, much of which goes over my head, admittedly. It was pretty neat to see the order of which it runs the different programs when compiling a ROM, though, and I’m impressed by the fact that you went through the effort to not just write a readme, but create a whole wiki dedicated to helping people better understand the took. Great work.
embed fail!!

I will admit that I'm kinda intimidated by command lines and I don't know if this program will ever get a GUI version but I can see braver folks than me making good use of it.

Originally posted by Heitor Porfirio
When you are doing a long time hack, for example since 2017, and you are doing the hack until 2023, but you want to update the Tools to not have problems, like PIXI, UberASM Tool, etc.
Would it be possible?

That depends entirely on whether your hack/resources are compatible with the new versions of those tools. Lunar Helper mostly just runs other tools in an organized manner, so it shouldn't have any bearing on whether your hack can use those tools or not.

Originally posted by FireSeraphim
I will admit that I'm kinda intimidated by command lines and I don't know if this program will ever get a GUI version but I can see braver folks than me making good use of it.

You don't actually have to be familiar with the command line at all to use Lunar Helper as it comes with a very simple menu in which you can just press a button on your keyboard to use the corresponding function. As such, there likely won't be a GUI version any time soon unless someone other than me thinks it's very necessary and decides to add it for some reason.
why is no one talking about the globules thing?? it's SO useful- i can't even conceive why it didn't exist sooner
this is gonna my life so much easier as an asmer, thank you so so much 💖💖 i'll def use this tool for all my hacking projects from now on-
Lunar Helper is extremely useful for building a hack, even if you're not inclined to use a git-based workflow. It's been very helpful for maintaining the romhackraces baserom, and I've been digging all the features underway has been adding. Very nice work and I'm looking forward to the future of this tool. #smrpg{<3}
Very neat, I am sure this will be helpful to a lot of people!

This is all really great stuff. Having separate build profiles is especially nifty. And setting up a wiki is really nice too. Documentation is so important, but usually a thankless job.
  • Pages:
  • 1
  • 2

Super Mario WorldTool