DDLC Mod Template Guide to Android Mod Making

Works on Ren’Py 6.99.12.4, 7.3.5 and higher.

Guide Version 1.3
Author: GanstaKingofSA#0235 | u/GanstaKingofSA

For DDLC Mod Template Versions: 2.4.0 and higher

Disclaimer: This guide is not endorsed by Team Salvato. Modding should be done when you
have completed DDLC. This is also not meant to port mods without author permission. Do not
port other people’s mods without their permission or release mods on Google Play, Galaxy Store,
etc.
DDLC Mod Template Link Download:
https://github.com/GanstaKingofSA/DDLCModTemplate2.0/releases

1|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 Contents
Setting Up The Template .......................................................................................................................3
Installation Steps .....................................................................................................................................6
Upgrading the Template..........................................................................................................................7
Building the Mod for Android ................................................................................................................8
Notes ......................................................................................................................................................... 10
FAQ............................................................................................................................................................ 13
Acknoledgements to ............................................................................................................................... 15

2|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 Setting Up The Template

To setup the template on a fresh copy of DDLC to use the Android feature, you will need the
following.
Note for MacOS Users: To access the contents of DDLC.app, right-click DDLC.app in MacOS
and click Show Package Contents.
1. A system with at minimum 8 GB of RAM.
a. Depending on the size of your mod, the RAM requirements listed here can
increase or decrease. Mods >500MB for all mod files + DDLC asset files (except
the RPAs) will need more than 4 GB RAM in order to build properly.

2. A new install of DDLC from either https://ddlc.moe or from Steam.

3. DDLC Mod Template Version 2.4.0 or higher

a. Please note this is only hosted on
https://github.com/GanstaKingofSA/DDLCModTemplate2.0/releases. This will
not work on the Monika-After-Story/RationalPi template or if you decompiled the
game yourself or with help from a guide. See Upgrading the Template for more
information.

4. renpy-6.99.12.4-sdk (Ren’Py 6) or renpy-7.X.X-sdk (Ren’Py 7)

a. If you are using Ren’Py 6 (6.99.12.4)
i. Download the Ren’Py 6.99.12.4 SDK by downloading it off
https://renpy.org/release/6.99.12 . Download either the 7z exe, dmg, or
tar.bz2 package for your respective OS and extract it somewhere.
b. If you are using Ren’Py 7 (7.3.5 or higher)
i. Download the Ren’Py 7.X.X SDK by downloading it off
https://renpy.org/latest.html. Download either the 7z exe, dmg, or tar.bz2
package for your respective OS and extract it somewhere.
c. Make a folder for your mod inside the extracted Ren’Py SDK folder.

5. Visual Studio Code (VSC)

a. It is recommended to install the Ren’Py extension in VSC. To do so go to
Extensions (Button with 4 boxes on the left side), search Ren’Py and install the
Ren’Py extension.

3|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 6. AdoptOpenJDK 8
a. Download AdoptOpenJDK 8 from
https://adoptopenjdk.net/?variant=openjdk8&jvmVariant=hotspot
b. Install everything except IcedTea-Web via the AdoptOpenJDK installer.

i. Note: Building your mod while having AdoptOpenJDK 8 & 11 installed

may cause problems. See the Notes Section 4 for more information.

7. RPATool
a. You can download RPATool from
https://github.com/Shizmob/rpatool/archive/master.zip.

8. Python 2.7
a. You can download Python from
https://www.python.org/downloads/release/python-2718/
b. Make sure to check Will be installed on local hard drive for Add python.exe to
path while installing Python 2.

9. An android phone with USB Debugging On or Android Studio for debugging errors,
testing, etc.
a. If you are using your own android phone:
i. To turn on USB debugging, go to Settings -> About -> Software
information and tap Build Number 5-8 times repeatedly until it says
Developer mode has been enabled. Then go back to Settings -> Developer
options and scroll down till you see USB debugging and turn it on.
1. A prompt may appear saying do you want to trust your computer
for USB debugging after you plug your phone into your computer.
Say Yes to it.
2. This step may differ from device to device. Consult your phone’s
manufacturer, XDA Developers or Google for more information.
4|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 b. If you prefer to use Android Studio instead:
i. Make sure to have Android Virtual Device checked during setup and
install everything (including Intel HAXM or the AMD equivalent). Next,
create a project, go to Tools -> AVD Manager and click the Play button to
start a virtual android phone for debugging use.

5|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 Installation Steps

Note: If you are upgrading your template to 2.4.X, followed a guide, or used a tool to make
your mod project, please read the Upgrading the Template section carefully.
1. Open the ddlc-win.zip file and double-click the DDLC-1.1.1-pc folder. Copy its contents
to the folder you made in the Ren’Py SDK folder.
a. MacOS Users with a ddlc-mac folder
i. Copy the contents inside the ddlc-mac folder to the folder you made in the
Ren’Py SDK folder.
b. MacOS Users with a ddlc-mac.zip file
i. Open the ddlc-mac.zip file and copy its contents to the folder you made in
the Ren’Py SDK folder.

2. Open the mod template ZIP file and copy its contents to the folder you made in the
Ren’Py SDK folder. Accept any replaces.
a. MacOS Users with a DDLCModTemplate-2.4.X folder
i. Copy the contents inside the DDLCModTemplate-2.4.X folder to
DDLC.app/Contents/Resources/autorun. Accept any replaces.
b. MacOS Users with a ddlc-mac.zip file
i. Open the ddlc-mac.zip file and copy its contents to
DDLC.app/Contents/Resources/autorun. Accept any replaces.

3. Open the rpatool-master ZIP file and double click the rpatool-master folder. Copy
rpatool to the game folder.
a. MacOS Users with a rpatool-master folder
i. Copy rpatool from within the rpatool-master/rpatool-master folder to
DDLC.app/Contents/Resources/autorun/game.
b. MacOS Users with a rpatool-master.zip file
i. Open the rpatool-master ZIP file and double click the rpatool-master
folder inside the ZIP. Copy rpatool to
DDLC.app/Contents/Resources/autorun/game.

4. Run DDLC via DDLC.exe, DDLC.app, or via the Linux Terminal by typing ./DDLC.sh
in the directory it is in.

5. If the game runs without any errors, you can exit it and proceed to make your mod and
follow the rest of the guide to setting variables and building your mod for Android.
6|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 a. If DDLC doesn’t start after a bit for the first time, try launching DDLC once
again. If it still refuses to start, take a look at traceback.txt for the error or send a
Issue Request to the DDLCModTemplate2.0 Github Repository.

Upgrading the Template

Upgrading from the Monika-After-Story/RationalPi Template (Versions 0.2.0 to 1.1.2)

This update like the original 2.X.X updates in 2019 has major code changes to be like DDLC
which the Monika-After-Story/RationalPi template lacks: especially the android code for this
update. It is highly suggested to move all your existing code to the 2.4.X files to retain all DDLC
functionality, your past work, and have Android compatibility in your mod.

Upgrading from Versions 2.1.X to 2.3.1 (includes 2.3.1-uX versions)

Due to the Android code, some functionality will require a transfer of code as well to 2.4.X. I
suggest transferring the code you have done to the 2.4.X files to retain your past work and have
Android compatibility in your mod.

Upgrading from Versions 2.4.0 to 2.4.4

This update doesn’t affect these versions too much as the Android code already in the template
has just been optimized to be simpler and fix some issues. If you do plan to upgrade, please note
the following.
• package_name in options.rpy has now become obsolete in this build in favor of
environment paths.
• script-poemgame, splash, script, options, and definitions.rpy have changed a bit with it’s
Android code similar to what was explained with package_name.
•
Android by following a DDLC Guide (Tormuse’s Mod Guide, etc.)
Some DDLC guides will show you that in order to make your first DDLC mod, you will have to
download decompiled scripts or show you how to decompile them with RPATool. This however
will not make your mod work on Android as it needs Android specific code for the game to run
properly under Android. If you plan to make your mod work on Android, do not decompile the
game or download these files and just rely on the mod template files itself for your Android mod
and this guide to help you make your mod work on Android.

7|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
Android via a tool-made project (DDMMaker [New DDMM])
If you made your project in DDMMaker, you should be fine following this guide as the tool uses
the correct mod template. Any other future tools made may or may not work with this guide’s
steps, it’s provided mod template and such.

Building the Mod for Android

Read the steps carefully before doing anything. This section assumes you only followed the steps
in Installation Steps and read the Upgrading the Template section.
Note for DDMMaker [New DDMM] Users: When following this guide, refer to Ren’Py
Launcher as DDMMaker [New DDMM].
1. Open Terminal, Command Prompt or PowerShell in the game folder and run the
following commands. Make sure you backup your mod files before your run them or
they might get overridden with DDLC’s own files.
a. python rpatool -x audio.rpa
b. python rpatool -x fonts.rpa
c. python rpatool -x images.rpa
i. If you get a Python was not found and not a ‘python’ is not recognized
error, see Notes, Section 7 for more information.
ii. If you get a ‘python’ is not recognized error, then Python is not installed
properly. Refer to Setting up the Template Section 8 and its details for
more information.
iii. Keep the RPA files in the game folder! At minimum remove the archive
check in splash.rpy if you must or Ren’Py will not compile your mod due
to a DDLC archive error. Don’t worry, the RPAs won’t be included in the
final APK release.

2. Start Ren’Py Launcher and select your mod from the Projects Sidebar, then click
Android.
a. You will be asked to download RAPT (Ren’Py Android Platform Tools). Select
Yes and it will download it. It will restart Ren’Py Launcher after it installs.

3. Go back to the Android section and click Install SDK and Select Keys. It will download
the Android SDK and other files. Accept the Android Terms and say Yes to setting up a
key and to backing it up. Set your organization name to your name.
a. If the Install SDK and Select Keys is grayed-out, you are either missing
AdoptOpenJDK8 or misconfigured it. Refer to Setting Up The Template Section
6 for more information along with Notes Section 4 for issues related to
AdoptOpenJDK8 and AdoptOpenJDK11 on the same system.

8|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 4. Click Configure and follow the steps below to setup the mod configuration for Android.
i. For Full Name, set it as your mod name.
ii. For Short Name, set it to your mod name’s abbreviation.
iii. For Package Name, use com. then your name with a period and the build
name of your mod. For example, if your name is Eileen and your build
name for your mod is TheQuestion in options.rpy (under build.name), it
will be formatted like this: com.eileen.thequestion
iv. For Application Version, set it to the version number of your mod.
v. For Version Code, leave it as is.
vi. (For 7.4.5 and higher) For RAM Allocation to Gradle, leave it as-is.
1. If you run into java.lang.OutOfMemoryError when building your
mod, return to Configure and increase this number. Remember to
not exceed your computer’s RAM size. Refer to Notes Section 5
for more information.
vii. For Display, set it to landscape orientation.
viii. For app store in-app purchasing, select Neither.
ix. Select No to creating an expansion APK.
x. (For 6.99.12.4) For version of Android, select Android 4.0.
xi. Select No to allowing the mod to access the internet.
xii. (For 7.3.5 or higher) Select Yes to automatically update your project.

5. Select Build Package and your mod should compile to a APK to be used on Android.
You may then sideload it to your phone and test it for errors before release.
a. For Ren’Py 6, your mod will be compiled with the following name format. Here
is an example with mod name Cookie Club and version number 2.3.0
i. CookieClub-2.3.0-release.apk
b. For Ren’Py 7, your mod will be compiled and output 4 APK files. For universal
compatibility between different phones, use the following name format APK.
Here is an example with author name Natsuki, mod build name mlhnstlc and
version number 1.0.0
i. com.natsuki.mlhnstlc-10000-universal-release.apk
c. Refer to Notes Section 5, if you encountered a java.lang.OutOfMemoryError
when building your mod.
d. Refer to Notes Section 1 & 2 if you can’t install your mod’s APK file due to pop-
up concerns.

6. After you tested that your mod works as is, upload it to Google Drive, Mega, etc. and
your port should be complete.
a. Make sure to add to your post that the user must turn on Unknown Sources on
their phones temporarily and of a Google Play Protect warning that may occur
and to tap Install Anyways. In addition, Google will ask to send the APK over to
9|Page
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 them. This does not break the IPG so in my opinion, just tell them to tap Send and
it will be good to go. Refer to Notes Section 3 for more details.

Notes

1. When installing your mod either via a file manager or by downloading off your browser,
etc. you may get this pop-up by Android or something similar.

To fix this, tap Settings and turn on Unknown Sources. Android will warn you that installing
apps from unknown sources may be malicious and some devices allow you to turn this on
temporarily which is fine. Select either OK or Install Just Once then select Install.
• This step will differ from device to device. Consult your phone’s manufacturer, XDA
Developers or Google for more information on turning on unknown sources.

2. When installing your mod either via a file manager or by downloading off Chrome, etc.
you may get this Play Protect pop-up.

10 | P a g e
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 This is Google detecting that you are someone they do not recognize as a developer and think
the app may be malicious. Tap Install Anyway and the installation should proceed as normal.
3. While running the game you might get a pop-up that asks whether to send your mod’s
APK file to Google for analysis. You can choose either option presented as this is just a
Google Security Message.

4. If AdoptOpenJDK8/Java JDK 8 and AdoptOpenJDK11/Java JDK 11 are installed, they

may cause an error in Ren’Py in which it cannot build your mod due to outdated code.
Please make sure that only AdoptOpenJDK 8 is installed (re-install it if
AdoptOpenJDK/Java JDK 11 is uninstalled) and if you still need AdoptOpenJDK/Java
JDK 11 as well, reinstall it after building is complete or build your mod on another
device/virtual machine.

5. Sometimes when building your mod, you may run into an error saying Caused by:
java.lang.OutOfMemoryError. This error is caused due to Java already using the
maximum space it can use for building the mod which is 3 GB. To fix this, go to
rapt/project and open gradle.properties with VSC. Change the three in -Xmx3g to a
different number. I recommend 5-8 but this depends on how much RAM there is on your
system. See Task Manager -> Performance, About this Mac, or neofetch to see how much
RAM you have. Allocate all but 1 GB of the system memory to it.

• If you are running Ren’Py 7.4.5 or DDMMaker [New DDMM] 1.2.6 or higher,
you can fix this within the Android Menu via Configure (Ren’Py Launcher and
later DDMMaker [New DDMM] versions) or Change RAPT Settings
(DDMMaker [New DDMM] 1.2.6)

6. When executing the RPATool commands in Windows, you might get this error.
Python was not found; run without arguments to install from the Microsoft Store, or
disable this shortcut from Settings > Manage App Execution Aliases.
To fix this, go to Windows Search and type Manage App Execution Aliases. In it, turn off
App Installer for python.exe. Next, reinstall Python and check on Will be installed on local
hard drive for Add python.exe to path and continue the installation. Once it completes, re-
open Command Prompt or Powershell and type the commands in again.

11 | P a g e
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 7. In some rare instances, RPATool may not work if you run the commands with Python 3
and Python 2 installed. To fix this, do py -2 instead of python and try typing the commands
again with it.

12 | P a g e
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 FAQ

Q. Where are all the game/character files located now?

A. They are located in the APK itself, however some files that can’t be loaded from it are copied
over to the Android/data/com.[yourname].[modbuildname] for deleting files, adding files, etc.
Q. A bunch of my scripts is broken. Why is it the case now?
A. Ren’Py on Android runs differently than on PC. There are different logical patterns needed in
Python in Android and such to run properly on all devices. Refer to the template comments or
the Ren’Py Documentation for more information.
Q. Does it have to be com.[yourname].[modbuildname] to build the mod? It looks cheezy and
bland.
A. No. You can change it to be whatever (except the modbuildname part), but it must follow the
Android naming scheme of x.y.[modbuildname] and be all lowercased. Consult the other folder
naming patterns in the Android/data folder on how to properly name an Android APK data
folder.
Q. My GUI elements are all broken. What gives here?
A. The GUI loaded is of DDLC but modified to work on mobile devices. The code for it is
located at the bottom section of gui.rpy. Change the variables there to adjust your GUI to how it
is in-game on PC.
Q. Isn’t distributing the APK with DDLC files against Team Salvato’s IPG?
A. No. Team Salvato acknowledges that this is a limitation on making DDLC mods available on
Android and allows it for the time being, however they will keep an eye on how these APK files
are distributed and Android modding may be revoked at any time by Team Salvato.
Q. What is the difference between this and JoiPlay?
A. This runs natively on Android rather than emulating a computer. This means it is prone to less
bugs and crashes than running mods on JoiPlay which is known to break many mods. Any errors
that appear are either the mod itself being packaged incorrectly or not coded to run differently
formatted code for Android.
Q. How would I add my files that need to be read, written to or modified in
Android/data/com.[yourname].[modbuildname] folder like the character files?
A. The mod template files shows some examples on how these files work in the game under
Android. Below are a few examples of code that writes files into the Android directory.

13 | P a g e
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
This code below shows an example of writing CAN YOU HEAR ME.txt to the game’s Android
directory.

This code below shows an example of writing the character files into the characters folder if a
Doki’s character file is missing from within the Android directory.

This FAQ is not an exhaustive list of questions for Android DDLC modding development. For
further questions, ask in the #mod_help channel or see the #mod_faq channel on the DDMC
Discord linked here or contact me in DM for any analysis of what might be wrong. Be advised
that not many members will know about Android modding for DDLC and support for it is
limited. Explain in depth the issue and someone will try to assist you.
DDMC Discord Invite: https://discord.gg/Gx7m9xE
14 | P a g e
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.
 Acknoledgements

I want to acknowledge the following people for assistance, either voluntary or in-voluntary.
Tom Rothamel i.e. PyTom for Ren’Py and Ren’Py Android functionality.
Dan Salvato for making DDLC and allowing us to mod it to our hearts content that is IP
compliant.
My past projects to optimize the mod template with better code.
You for reading this whole guide.

Weiss Schnee for support. (Weiss: �)

15 | P a g e
Copyright © 2020-2021 GanstaKingofSA. All rights reserved. Doki Doki Literature Club (DDLC), the Doki
Doki Literature Club Code is the property of Team Salvato (Dan Salvato LLC). Copyright © 2017 Team
Salvato. All rights reserved.