[Guide] Adding Backgrounds -- rough draft, may contain errors!

[lunulae]

NOTE: This is now outdated! Please check the wiki for updates.

Welcome to a complete newbie's guide to the MAS location system!

This guide is intended for those who, like me, have little to no coding background. If you have more experience, feel free to skim through for what info/steps you need!

[edit: I'm currently having some issues adding screenshots, I will try to get them included in the near future! Also... my god, this ended up being a lot to type in one go. I have checked it over for any major errors but please let me know if I've missed things]

Important!: For the sake of simplicity, I am going to be referring to the main folder where MAS is kept as DDLC. Yours may be named differently (mine is DDLC-1.1.1-pc) depending on the version of DDLC you're running or if you renamed the file. It can be any name, just know that it will be referred to as such in this tutorial.

Step 1: Folders and Files You Need To Know

This step is most important if you have never added any submods or altered any graphics in MAS. For adding backgrounds, we are going to need to understand just two file directories inside MAS.

The first thing we're doing to do is set up a submod folder. This is where you'll keep any RPYs we make later in this tutorial. This will be located in the game folder of DDLC. So this directory would look like DDLC/game/submods. It should be empty unless you have already added other submods, of course!

The second file we're going to look at is _DDLC/game/modassets/location. If you look inside this folder, you will see other folders inside, such as one for the spaceroom. We're not going to edit the spaceroom files, but we will be going back to them as a reference point and template for our new locations.

Step 2: Unlocking the Background Selector

Currently, the background selector topic is locked by default. Most of the framework for it is already in-game, we just need to add in the option to select the topic.

Doing this is simple. Open Notepad (or your code-editing program of choice) and create a file that contains this code:

init 5 python:
    addEvent(
        Event(
            persistent.event_database,
            eventlabel="monika_change_background",
            category=["location"],
            prompt="Can we go somewhere else?",
            pool=True,
            unlocked=True,
            rules={"no unlock": None},
            aff_range=(mas_aff.AFFECTIONATE, None)
        )
    )

Save this as a .rpy file and put it into DDLC/game/submods. You can name it whatever you wish, such as backgroundunlocker.rpy.

This works the way it does because the background topic already (partially) exists inside the _zzbackgrounds.rpy file. The above code allows us to use it as a "Hey, Monika..." topic. Once we've added backgrounds, it should appear under "Hey, Monika...>Location>Can we go somewhere else?".

[Note to mods: I'm not sure if this by itself should unlock the selector, or if backgrounds need to be added first for it to be seen at all.]

Now we've done what we need to start adding new backgrounds of our own! This is where things get more advanced.

Step 3: Images and Editing

I'm assuming if you are reading this tutorial, you have an image already that you would like to use as your background. For the sake of this tutorial I'll be using MC's room, which you can find on the DDLC wiki.

Looking inside the spaceroom folder, you might notice that there are a lot of variants of the spaceroom image in there! Ones for different times of day, and each kind of weather. If you would like, you can use all of these different variants to make your background dynamically change with each weather type! However, the only ones that are absolutely required are a day and night version. Once you have those versions, you're ready for the next step!

Some things you might want to know for your image editing:

• If you would like your night edits to look uniform with the spaceroom, the justtwilight.psd filter is what you're looking for.
• You should make sure that your images are the same size/resolution to the spaceroom files (1280x720.) This is not strictly necessary, but an oddly-sized image may cause graphical glitches or fuzzy resolution.
• Your images should be saved in .png format. [note: I'm not sure if this is the only accepted format, but it will likely give best results, especially if you have a background with transparent bits such as windows.]

Step 4: Image Names and Folders

From this point, file locations and names are going to become very important! This is because when we do the coding part, we'll need to tell MAS which files to use for our new backgrounds.

We're going to go back to the _DDLC/game/modassets/location file now. Then we're going to make a folder with the name of whatever location you want to use. Inside this folder, we're going to add your day and night variants (and other weathers if you have them.) Then we're going to make the names match the files in the spaceroom folder.

For example, the default night spaceroom image is called spaceroom-n.png My bedroom file would then be bedroom-n.png

So at the end of this, I have _DDLC/game/modassets/location/bedroom which contains bedroom.png and bedroom-n.png.

Step 5: Coding Your New Room

If we look at the zz_backgrounds.rpy we see that there's a framework in place to set up backgrounds that looks a little something like this:

        def __init__(
            self,
            background_id,
            prompt,
            image_day,
            image_night,
            image_rain_day=None,
            image_rain_night=None,
            image_overcast_day=None,
            image_overcast_night=None,
            image_snow_day=None,
            image_snow_night=None,
            hide_calendar=False,
            hide_masks=False,
            disable_progressive=None,
            unlocked=False,
            entry_pp=None,
            exit_pp=None
        )

That looks really daunting, I know! But rest assured, these are actually very easy to understand when we break it down. Explanations are even provided on the file for what each one does, and we can compare to the spaceroom if we need a reference. To make it even simpler, I'm going to break it down into pieces.

Take that big wall of code and paste it into a new notepad file. This is going to become the RPY file where you list your locations, (if you like it can even be the same file as the one you used to unlock the background selector. Just paste that text a few lines down.)

For def__init__( we're going to put init -1 python: so that it matches the spaceroom example. [note: I have no idea why this works the way it does, all I know is that it does]

Next we have

            self,
            background_id,
            prompt,

[edit; the below paragraph is somewhat inaccurate, but the file should still look correct. Will adjust my explanation when I'm able] self and background_id are labels for MAS, to understand that this is a background file. On the spaceroom example we can see that this is set as mas_background_spaceroom = MASBackground( So instead of spaceroom, we're going to replace self with mas_background_bedroom = MASBackground(

background_id should be the name of whatever your background is. This must be a unique name, so just don't name it spaceroom.

prompt is the name that will show up on the location list inside MAS. You can name this whatever you like, such as "Bedroom" or "Your Room"

So, we should currently have inside your new file:

init -1 python:
    mas_background_bedroom = MASBackground(
        "bedroom",
        "Bedroom",

Next we're going to look at a bigger chunk of the code.

            image_day,
            image_night,
            image_rain_day=None,
            image_rain_night=None,
            image_overcast_day=None,
            image_overcast_night=None,
            image_snow_day=None,
            image_snow_night=None,

These are all indicators of your different weather/time variants. If you have only a day and night variant, the only ones you need to change are image_day and image_night. These can be any label you want to use, for the sake of this tutorial I'm just going to use bedroom and bedroom_n.

If you only have day and night variants, your file will look like this so far:

init -1 python:
    mas_background_bedroom = MASBackground(
        "bedroom",
        "Bedroom",
        "bedroom",
        "bedroom_n",

If you have other weather variants, the format is going to change a little. Rather than entirely replace the line with your image name, you're going to replace the None with your image name. For example, image_rain_day=bedroom_rain,

If you don't have a weather variant, you can ignore that line or delete it entirely.

We're almost set now, but there are a few more important lines.

            hide_calendar=False,
            hide_masks=False,
            disable_progressive=None,

hide_calendar does exactly what it sounds like. If you don't want your background to include the calendar, you will set this to hide_calendar=True

hide_masks is important if you have transparent parts of the background that you would want to see the weather through, such as windows. If it is set to hide_masks=False, you will be able to see weather. My bedroom background does not have any windows, so I will be setting mine to hide_masks=True

disable_progressive has to do with progressive weather. If you want the weather to never change while you are in this location, you would set it as disable_progressive=True I still would like to occasionally hear rain while in the bedroom, so I will be setting it to disable_progressive=False

So now my file looks like this:

init -1 python:
    mas_background_bedroom = MASBackground(
        "bedroom",
        "Bedroom",
        "bedroom",
        "bedroom_n",
        hide_calendar = True,
        hide_masks = True,
        disable_progressive = False,

Now we're in the final few lines!

            unlocked=False,
            entry_pp=None,
            exit_pp=None
    )

unlocked is pretty simple--we want this background to be unlocked, so we set it as unlocked=True

entry_pp and exit_pp have to do with programming points--and I'll be honest, I don't actually know what they do yet. They're not necessary for a basic background change, so I'll leave them out for now. Make sure you keep that ) at the end to close things up.

So my bedroom file now looks like

init -1 python:
    mas_background_bedroom = MASBackground(
        "bedroom",
        "Bedroom",
        "bedroom",
        "bedroom_n",
        hide_calendar = True,
        hide_masks = True,
        disable_progressive = False,
        unlocked=True
    )

We only have one last thing to add and we're done. We just need to show MAS where to find our images. It already knows that everything will be somewhere in the game file, so we only need to direct it from mod_assets onward.

We're going to use whatever labels you used for image_day, image_night and other weather variants if you have them. Mine looks like this

image bedroom = "mod_assets/location/bedroom/bedroom.png"
image bedroom-n = "mod_assets/location/bedroom/bedroom-n.png"

This can be placed right below your location code. My final file looks like this:

init -1 python:
    mas_background_bedroom = MASBackground(
        "bedroom",
        "Bedroom",
        "bedroom",
        "bedroom_n",
        hide_calendar = True,
        hide_masks = True,
        disable_progressive = False,
        unlocked=True
    )

image bedroom = "mod_assets/location/bedroom/bedroom.png"
image bedroom_n = "mod_assets/location/bedroom/bedroom-n.png"

Save this as a .rpy and pop it into your DDLC/game/submods folder.

Now, at long last, you can start up MAS, and enjoy your new background!

[multimokia]

So first things first, in your code blocks you've put, I'd make them start with the renpy keyword (so after the 3 `'s add renpy to it, it will give it syntax highlighting.

re:

self and background_id are labels for MAS, to understand that this is a background file.

So, self isn't actually something entered, it's just something always a part of __init__. The first item that's in the constructor is actually the background_id when you fill it out yourself.

re:

entry_pp and exit_pp have to do with programming points--and I'll be honest, I don't actually know what they do yet. They're not necessary for a basic background change, so I'll leave them out for now.

Programming points are essentially a way of running code on background change (entry being when changing into the background, exit when changing out of the background) useful if you need to lock/unlock certain topics when going into/out of a bg.

[satoshi-kun]

Hello! Beforehand I'd like to thank you for your guide! It is easy to follow even for a pleb like me :) Still after several errors that I managed to correct I still can't get the option to change the background even though I've followed STEP 2. Thanks again!

[ghost]

Thank you for posting this guide! I love being able to extend the functionality of the game, and being able to add new locations to visit is awesome.

Hello! Beforehand I'd like to thank you for your guide! It is easy to follow even for a pleb like me :) Still after several errors that I managed to correct I still can't get the option to change the background even though I've followed STEP 2.

@satoshi-kun I had the same trouble and after a bit of playing around I noticed that in Step 2 where we unlock the background selector, it says: unlocked=False. So I changed it to unlocked=True. Still didn't work though, until I removed the 'rules' line that follows. That did the trick for me. That portion of code now looks like this:

background unlocker.txt

I hope it's OK to post this here, if not please let me know and I will remove it. Thanks again for your hard work!

[multimokia]

Ah I see the issue

Basically, you want to keep the rules field, but set unlocked=True from the get-go.

@d3adpan I just edited your comment to use a code block to make it neater. But yeah, what you want is:

init 5 python:
    addEvent(
        Event(
            persistent.event_database,
            eventlabel="monika_change_background",
            category=["location"],
            prompt="Can we go somewhere else?",
            pool=True,
            unlocked=True,
            rules={"no unlock": None},
            aff_range=(mas_aff.AFFECTIONATE, None)
        )
    )

[ghost]

Thanks @multimokia! I edited it before I saw your comment, to include a .txt file of the modified .rpy

I still can't get it to work with the adjusted rules field, but removing or commenting out that line works. I'm out of my element so thank you all for the help!

[lunulae]

omg, I can't believe I didn't notice that when I was looking it over for errors. Once I get back home I'll make all of those edits, thank you all so much for the help!

I made a few formatting edits, Step 2 should be correct now.

[satoshi-kun]

Thank you all so much! Can't wait to try it once I finish work.

By the way, I may have encountered an error related to:

If you have other weather variants, the format is going to change a little. Rather than entirely replace the line with your image name, you're going to replace the None with your image name. For example, image_rain_day=bedroom_rain,

where I believe that the image name has to be inside quotation marks, image_rain_day="bedroom_rain",

But still is better to double-check with someone more "progamming savy".

Thanks again!

[satoshi-kun]

Hi again! I finally got it working but only after removing the rulesline. I tried to only change unlocked=True but nothing happened. After I deleted the rules line the option to change location appeared. Thanks for all the help!

[multimokia]

that's because of the way "no unlock" works. Random pool topics are unlocked for events without the rule, to do it otherwise, you need to do

mas_getEV("monika_change_background").unlocked=True to have it unlock. (You only need to do it once)

[ghost]

That's why I couldn't reproduce it! It was driving me crazy, thank you for clarifying the event unlock rule.

If you have other weather variants, the format is going to change a little. Rather than entirely replace the line with your image name, you're going to replace the None with your image name. For example, image_rain_day=bedroom_rain,

where I believe that the image name has to be inside quotation marks, image_rain_day="bedroom_rain",

I ran into the same trouble when adding additional images - it does need to be in quotations and then defined at the bottom along with the other images, like so:

image bedroom_rain = "mod_assets/location/bedroom/bedroom_rain.png"

[multimokia]

Also

    image bedroom = "mod_assets/location/bedroom/bedroom.png"
    image bedroom-n = "mod_assets/location/bedroom/bedroom-n.png"

the -n extension on image tags shouldn't be used as it's bad form (- is normally an operator), best to use an underscore, so image bedroom_n = "mod_assets/location/bedroom/bedroom-n.png"

[ThePotatoGuy]

should move this to the wiki so we can have a toc

[lunulae]

I've made a few more minor edits, but there are a few things I wasn't sure how to explain so I've left them for now. If y'all would like to move it to the wiki I am happy to do so, please feel free to make adjustments and rewrite things as much as you'd like. There are quite a few big gaps in my knowledge.

[satoshi-kun]

@lunulae I would say you did a great job considering I was able to add my backgrounds without knowledge of programming (aside from some HTML and css). I couldn't be happier. Thanks for the guide!

[multimokia]

Didn't notice your comment ages back, feel free to add to the wiki, we'll adjust it as the api changes slightly. As of right now this is still accurate though

[lunulae]

I copied it over to a wiki page, please feel free to edit anything that still sounds clunky or inaccurate in here. Thanks again! <3

[multimokia]

I have made the edits

[multimokia]

@lunulae can you send me an email please? My email address is on my profile.

[lunulae]

Closing this now that it's on the wiki, thanks so much for everybody's help. :D