Life in the Woods Renaissance Launcher

Launcher and Helper Mod Manual

Version 1.3.12

07-Sep-2019

Holger Machens

This is the user manual of the launcher for Life in the Woods: Renaissance. The launcher was developed to ease installation and update of the mod-pack and addons like shaders. However, the launcher is not necessary to run Life in the Woods Renaissance. You can also download and install the mod-pack manually from the web-site.

Contents

Installation

This section will guide you through the installation of the launcher. The launcher requires Java SE 1.7 minimum and comes in a package with installation scripts for all supported platforms (Windows/MacOS/Linux).

Prerequisites

Minimum requirement for the mod-pack is Oracle Java SE 1.8 either the JDK (required on Mac) or the JRE package. It is also recommended by Mojang to use the latest Java version for better performance. Download Java 1.8 here. In case that link is no longer valid go here and navigate to Java SE (which means "Standard Edition").

Easiest way for Ubuntu/Debian users are the WEB UPD8 PPA packages, see: WEB UPD8

• If you are running a 64bit architecture, then you have to have a 64bit Java as well!
• Oracle is necessary: Neither the Launcher nor Minecraft will run properly with non-oracle Java environments such as OpenJDK or Apple Java.

However, the installation scripts will check first if all those requirements are met.

Download

The installation package of the launcher can be found here. If you consider a manual install of the mod-pack only, visit the download page on the official web-site of Life in the Woods Renaissance.

Windows

In order to install the launcher you have to perform the following steps:

1. Unzip the downloaded installation package (see Download) to a folder, where you want the launcher to be installed.
2. Run the installation script windows\install.bat. You can start the installation script with a double click. The installation script checks if you have a suitable Java installation and creates a shortcut on your desktop, that is all. You can move the shortcut to any location you like.

MacOS

In order to install the launcher you have to perform the following steps:

1. Unzip the downloaded installation package (see Download) to a temporary folder.
2. Run the installation script mac/install.command. You can start the installation script with a double click. If that does not work for you, then start the Terminal application (command line), navigate inside the unzipped folder, and execute chmod +x mac/install.command && mac/install.command. The installation script checks if you have a suitable Java installation and creates an Application Bundle with the launcher on your desktop, that is all. You can move the Application Bundle to any location you want.
3. Remove the unzipped folder when you are done. The launcher has been copied to the Application Bundle and the unzipped folder is no longer needed.

Linux

1. Unzip the downloaded installation package (see Download) to a folder, where you want the launcher to be installed.
2. Run the installation script linux/install.sh. You can start the installation script with a double click. If that does not work for you, then start a shell (e.g. xterm), navigate inside the unzipped folder, and execute chmod +x linux/install.sh && linux/install.sh. The installation script checks if you have a suitable Java installation and creates a desktop link in the top-level directory of the unzipped folder. This link should be compatible with most window managers of debian derivates (e.g. Ubuntu). You can move the desktop link to any location you like (e.g. menu or toolbar).

Platform Independent

The installation package contains the launcher's Java archive (litwrl.jar). If the above installation scripts did not work for you, then you can always start the launcher with the command:

		> java -jar litwrl.jar
		

Make sure you have at least Oracle Java SE 1.8 installed (see Prerequisites).

Application

Start

When you start the launcher you may experience a short delay of 1-2 seconds without a visual feedback until the graphical user interface (GUI) shows up.

Especially during the first start the launcher will then need some time to initialise its local directory (see Section Directories). This will be indicated with the text "initialising .." on the button in the center of the footer in the GUI (see Section User Interface).

User Interface

The GUI of the launcher is basically subdivided into a header, a center and a footer.

Header

The header, which also shows the LitWR logo, allows you to switch between the different tabs, namely News, Config, Log, Credits and ? (the help page).

Center

The center shows the content of the selected tab. In the Figure you see the content of the selected tab News.

Footer

The footer contains (from left to right) the progress bar, the Install/Play button and the variant selector. The Install/Play button is used to start an installation/upgrade of a game and to start an installed game. The variant selector is used to select one of the two variants of Life in the Woods Renaissance (see Section Game Variant for details).

Tab Sheets

The GUI provides the following tab sheets:

News

The launcher will always start with the News tab selected to show you recent news related to Life in the Woods Renaissance.

Config

The configuration page allows you to configure your game installation (see Section Configuration).

Log

The Log tab shows you messages of the launcher which provide detailed information about ongoing tasks. This tab will be automatically opened during installation or upgrade to give more feedback about what's actually going on. However, you can always switch to another tab.

Credits

This tab provides links to all the organisations and people somehow involved in the creation of Life in the Woods Renaissance or related components, artwork etc..

? (Help Page)

This tab contains a brief getting started guide for newcomers and links to available documentation for all mods which alter the game play.

Directories

This sections explains which directories are used by the launcher on your system and where you can find things you know from Minecraft.

Launcher Bootstrap Directory

This is the directory, you have originally unzipped from the installation package you have downloaded. Respective on MacOS this is the Application Bundle that was created by the installation script. The bootstrap directory contains a copy of the launcher which is used to boot into the latest version of the launcher. So, when you have just downloaded the launcher, the bootstrap and the latest version of the launcher will be the same. With updates this will change.

Launcher Local Directory ( $HOME/.litwrl)

The local directory is located in your home directory (Windows: C:\Users\<login>\.litwrl, MacOS: /Users/<login>/.litwrl, Linux: /home/<login>/.litwrl). The local directory contains almost everything the launcher needs to operate and to run Life in the Woods Renaissance.

• litwrl.cfg: Configuration file of the launcher.
• litwrl.log: Log file of the launcher, with the same contents shown in Log tab.
• repository: Local cache of mod-pack information (dependencies, versions, etc.) and data (downloaded files). It also contains the latest version of the launcher itself.
• games: This directory contains the modded game installations for Life in the Woods Renaissance. For example if you have installed Life in the Woods Renaissance in variant Basic, then this directory will contain a game directory LitWR.Basic with all mods and shader etc. in it.
• minecraft (optional): By default, the launcher will create its own Minecraft installation in its Local Directory. You can change that on the Config tab.

Minecraft Working Directory

By default, the launcher will create its own installation of Minecraft in its Local Directory (see above). You can also choose to use your own minecraft installation on the Config tab (see Configuration).

Game Directory

The game directory was already mentioned under Launcher Local Directory. Game directories created by the launcher are located in the subdirectory games in the launchers local directory. A game directory contains mods, configs, saves, screenshots, shaderpacks and more of a game installation of Life in the Woods Renaissance. Since there are two different variants of game configurations, you may have two different game installations in this folder: LitWR.Basic and LitWR.Hungry (see Sections Game Variant for more).

Install and Start a Game

When you start the launcher for the first time, it will be preconfigured to install Minecraft and Life in the Woods Renaissance in variant Basic without shaders in its local directory. You can start the installation process by clicking on the Install/Play button in the footer of the GUI (see Section Interface). When the installation is finished the Install/Play button will change to Play and you can click it again to start the game.

The following sections will explain the different game variants and configurations you can chose for installation.

Game Variant

Life in the Woods Renaissance comes in two variants: Basic and Hungry. Both refer basically to different levels difficulty based on modifications of hunger and food/growth mechanics. Basic can be considered as standard and Hungry as difficult.

The variant selector (lower right corner in the GUI) selects the variant you would like to install/play. You can have both installed and switch between them but they will not share the same worlds. When you connect to a server it is not necessary to select a specific variant, they are both compatible with certain variant running on the server.

Configuration

The configuration of a game variant can be viewed and edited in the Config tab (see below). This section will explain the different elements on the Config tab beginning at the top.

User

The launcher supports multiple user accounts. The drop down box allows to switch between known user accounts. During installation, the launcher will copy the user accounts of your standard Minecraft installation and automatically select the one you have recently used. If you would like to add another account, then chose the field "login on next start". The launcher will then open a login prompt when you start the game.

Working Directory

This field contains the path to the Minecraft working directory (see also Section Directories). You can change this path either by editing or via a click on the folder icon to the right.

• If you have chosen a folder which does not exist or do not contain a Minecraft installation, the launcher will create a new Minecraft installation at this location.
• If you have selected a path to another Minecraft installation (e.g. your normal Minecraft installation), then the launcher will detect it and install just missing files (such as the required Forge version) and add profiles for the Life in the Woods Renaissance games you have installed. In case you switch back to your Minecraft installation, you will then have to select the profile you would like to use in the lower left corner of the Minecraft launcher window.

By default, the launcher will create its own Minecraft installation in his local directory. This prevents the launcher from any modifications or anomalies that might exist in your normal Minecraft installation. However, one disadvantage for you might be that you have to login again every time you switch between Life in the Woods Renaissance and your normal Minecraft installation. You can fix that by selecting your normal Minecraft installation in this field. The launcher will then share this installation with the Minecraft launcher and you will only have to login again if the authentication token is expired.

Variant

This field just displays the variant you have chosen with the variant selector in the lower right corner (footer) of the launcher GUI (see also Section Game Variant).

Version

This field displays the version of the selected variant of the mod-pack which is either currently installed or will be installed when you hit the Install/Play button. In case you are installing the mod-pack for the first time, this field allows you to chose one of the versions available on the update server. By default, the launcher will select the most recent version.

Behind the version field is a radio button showing the text Keep. In case the update server offers a newer version of the mod-pack, this button allows you to keep an already installed version until you decide to upgrade. This allows you to play with an older version until you think it is safe to upgrade. Also, when you first install a variant and select an older version, the launcher will automatically activate the Keep button.

Once installed, you cannot downgrade a given version of the mod-pack (just not supported). In case you want to check if an upgrade will be successful (considering an upgrade of a world you have used in an older version), then create a backup first: Copy the game folder (see above) to a save location. If you decide to keep the older version then copy the backup back to its original location and set the tick to Keep this version.

Profile

This field displays the name of the profile which is also the default name of the game directory (see Section Directories). The name of the profile always consists of the prefix LitWR. followed by the name of the variant. When you share your Minecraft installation with the LitWR launcher, this profile will also show up in the Minecraft launcher and you can safely start LitWR from there too.

Game Directory

This field displays the game directory of the selected LitWR variant (see Section Directories). By default the launcher suggests a location for the game directory in its local folder.

You can chose a different location for the game directory here. In this case, please note that the game directory is specific for the selected game variant and version. Do not use the same game directory for different variants. If you select an existing directory, the launcher will detect the version but not its variant.

JVM Arguments

This field contains the arguments which will be given to Java during start of the Minecraft client. When a game variant has been selected for the first time, the launcher analyses your hardware and adjusts these arguments to optimise performance.

JVM arguments have significant impact on the performance and can cause the game to crash or not start at all. You can always reset these arguments by clicking the Reset button below.

Optional Features Section

Shader pack and some of the mods are optional and require a seperate download. Thus they have got its own section on the config page. Optional features include a shader and the mods ShaderModCore and OptiFine to make the shader work, but also the mod DynamicLights, which lets torches emit light while holding them in your hand.

If one of those optional features is selected, the installation process will require you to download some packages through your Internet browser. But don't worry, the launcher will guide you and you will basically just have to click buttons and links.

Features can be enabled or disabled which results in either installation or deinstallation. In case of changes to the current configuration the Install/Play button will reflect this by showing the text Apply Changes. A click on this button will then execute the required operations to apply the changes.

Shader

This field generally allows you to select one of the supported shaders or those shaders, you have manually installed. The list of shaders is ordered by performance impact. The topmost are the lightest and the bottommost reduce FPS more. The empty field, or field none or internal represent Minecraft vanilla shading, i.e. no custom shaders.

When selecting a custom shader for the first, the launcher will automatically add all optional features as well. The ShadersMod is required by all shaders. Other features can be turned off in case your game runs better without them.

To support the Streams mod (generates flowing rivers) shaders are getting patched during the start of the Minecraft client. We have added patches for Sildur's shaders only, which is the main reason why we support just Sildur's shaders. You can always add other shaders, but they will not shade streams unless you add patches for them as well. Refer to Section Shader Patching in order to learn how you can add support for your shader.

Activation of shaders is twofold: It makes your game look prettier (at least for most people) but it reduces frames per second and game performance in general. Reduced FPS can cause motion sickness for some people, which you may experience as getting more or less dizzy. It is not dangerous but uncomfortable. We tried to find good general settings for the shaders we support but you may still have to adjust them for your system. If this is getting to fiddly or impossible, then just unselect the shader. Also, you may have to deal with some shader/graphics card issues that have been reported earlier. In this case refer to the FAQ to solve them.

Shaders Mod

If this tick is set, the launcher will install the Shaders Mod which is required for all shaders. In case a custom shader is selected, this tick will be automatically set.

OptiFine

OptiFine improves game performance even if you are not using shaders.

Dynamic Lights

This is a mod, which lets items emit light, even when you hold them in your hands wear them on your head or drop them on the floor. Downside is, that it can be quite resource intensive.

Reset Button

The reset button resets the JVM arguments and the Shader to its default settings. In case of the JVM arguments, that means that the launcher will reassess your hardware which might come handy in case you have added memory for example.

Helper Mod

Modifications to RuinsPositionsFile.txt

The Ruins mod maintains a database of generated ruins in the world save folder ( RuinsPositionsFile.txt). The helper mod allows to add a standard entry to this database each time a new world is created.
Available on server and client side.

Default World Type

LitWR uses Biomes O'Plenty as default world generator. To prevent confusion, the mod promotes Biomes O'Plenty to be the default world type. Users don't need to select the world type manually and the Biomes O'Plenty reminder notification can be suppressed.
Available on server and client side.

Solves Key Binding Conflict

OptiFine provides a zoom or binocular function. The default key for this functionality unfortunately conflicts with the default key binding for sprinting ( left CTRL). The mod detects this conflict and solves it by remapping the zoom key to Z.
Available on client side only.

Shader Patching

As explained in Section Shader, shaders have to be patched to support the streams mod. The mod provides a method to patch shaders dynamically (see Section Shader Patching for details).
Available on client side only.

LitWR Main Menu

The mod also adds the LitWR logo and theme music to the main menu.
Available on client side only.

Configuration

The helper mod uses a configuration file at the standard location suggested by Forge, which is:

		<game directory>/config/litwr.cfg
		

Please note that there is another configuration litwr-launcher.cfg which belongs to the launcher only.

If the configuration file does not exist, it is created at the first start of the Minecraft launcher and populated with default values. The configuration file may contain the following properties:

B:displayLitwrLabel

Boolean value, which controls whether the LitWR logo will be displayed in the main menu or not.
Default: true
Side(s): Client

B:exchangeDefaultWorldType

Flag, which controls whether the default world type will be exchanged with the one given in property S:newDefaultWorldType.
Default: true
Affected Side(s): Client and Server

S:newDefaultWorldType

The world type which will be promoted to be default.
Default: BIOMESOP
Affected Side(s): Client and Server

B:suppressBOPsNotifier

A boolean flag, which controls whether the mod will suppress the reminder notification banner of Biomes O'Plenty.
Default: true
Affected Side(s): Client

B:patchShaders

Boolean flag, which controls whether shaders will be patched or not.
Default: true
Affected Side(s): Client

S:ruinsPositionsInitialContent

A string which will be used as initial content for the file RuinsPositionsFile.txt.
Default: -1200 1 -1200 1200 250 1200 SpawnBlocker
Affected Side(s): Client and Server

B:solveZoomKeybindingConflict

A flag, which controls whether the mod will resolve a keybinding conflict between OptiFine's zoom key and the sprint key or not.
Default: true
Affected Side(s): Client

Example Config File

		general {
		    B:displayLitwrLabel=true
		    B:exchangeDefaultWorldType=true
		    S:newDefaultWorldType=BIOMESOP
		    B:patchShaders=true
		    S:ruinsPositionsInitialContent=-1200 1 -1200 1200 250 1200 SpawnBlocker
		    B:solveZoomKeybindingConflict=true
		    B:suppressBOPsNotifier=true
		}
		

Shader Patching

Based on block IDs, shaders decide which function they apply to shade blocks. For example many shaders differentiate between plants and solid blocks and manipulate the shape of plants to let them look like they are waving in the wind. Another example are water blocks which are shaded differently to apply reflections to the water surface.

Obviously, the shader can't shade blocks properly if it does not know the given block ID. Streams is a mod, which adds flowing rivers. To visualise the flow, streams adds a bunch of new blocks. Because those new blocks are unknown to the shader, they are not shaded.

A practical approach to solve this issue is, to determine the missing block IDs and add them to the branch, where the shader decides whether a block is water or not.

Unfortunately, the IDs of blocks introduced by mods, are issued dynamically by the mod loader (i.e. Forge). Thus, in different installations of the same mod, the IDs of its introduced blocks may be different. This means, the modifications made to the shader in one installation will not work in another installation.

To overcome this issue, the helper mod of LitWR introduces a functionality to patch shaders at the start of the client using a preprocessor. The preprocessor scans so-called shader patch template files for specific preprocessor statements and exchanges them by dynamically generated strings based on the installation and environment of the running Minecraft client instance.

Procedure

On each start the dynamic shader patch instance runs the following tasks for thoses shaders in folder "shaderpacks" which have a corresponding template patch file folder in mods/resouces/litwr/shaderpatch:

1. Backup: If it not already exists, a backup of the original shaderpack is stored in "mods/resources/litwr/shaderpatch/backups".
2. Unpack Original: The original shaderpack from the backup location is unpacked to a temporary working directory.
3. Preprocess Patch Templates: The shader pack's template patch files folder gets fed to the preprocessor. Its result is written to the temporary working directory in order to override existing original shader files.
4. Install Patched Shaderpack: When preprocessing is successfully finished, the result is packed again (zip) and moved back to the shaderpacks folder, replacing the shaderpack with the same name.
5. Reinitialise Shader: If the shaderpack was already loaded, it will be forced to unload and reinitialise with the patched shaderpack.

Patch Template Files

Patch template files are shader files which contain modifications in respect to the original shader file. Those modifications can for example be added preprocessor statements which will be replaced later on by the preprocessor (thus, the name patch template). Patch template files replace shader files at the same location in the shaderpack. Additional shader files will be copied to the patched shader pack as well.

A patch template file T for a given shader file O of the shader pack P has to be stored in the folder mods/resources/litwr/shaderpatch/P/T to replace the shader file shaderpacks/P/O.

Example:

Preprocessor Statements

Syntax:

Commands

Methods

Methods are actual methods of objects in the Java code of the mod. The following methods are supported:

Example:

		if (mc_Entity == 8 || mc_Entity == 9 
		/*#spp-paste " || mc_Entity == "*/
		/*#spp-call getBlockIds("streams:river/tile.water", "|| mc_Entity == ")*/
		) {
		    isWater = true;
		}
		

Troubleshooting

First Aid

The launcher developer maintains a support web-site. It features:

• FAQs to solve known issues,
• a list of filed bugs and feature requests,
• and instructions to report bugs or request features.

Switch to Vanilla Minecraft Launcher

In case you need certain features not supported by the LitWR Launcher you can easily switch to the vanilla Minecraft Launcher following this guide.

By default the launcher creates its own Minecraft installation to keep things separated. The easiest way to switch to the vanilla Launcher is to use the vanilla Minecraft installation instead.

1. Start the LitWR Launcher
2. On its config tab change the working directory to point to the vanilla Minecraft directory.
3. Hit the Install button. This will install the required Minecraft version and Forge in your vanilla Minecraft directory and creates a profile entry according to your current settings.
4. Close the LitWR launcher.
5. Start the vanilla Minecraft launcher.
6. In the lower left corner of the window, select the LitWR profile which was created by the installation. The name of the profile depends on the game variant you have chosen, i.e. LitWR.Basic or LitWR.Hungry.

You can now start and configure the game with the vanilla Minecraft launcher.

Security and Privacy Statement

Privacy

Neither the launcher nor the helper mod gather or distributes any kind of information about the user or his system. The launcher just downloads files and has no other communication related functions.

Downloads

The launcher communicates with various source on the Internet to receive files. To prevent injection of malicious code, the launcher does checksum check on downloaded files where possible. An exception are for example Sildur's shaders, because they update from time to time without changing its version number and/or download location. Thus, we cannot do checksum checks without breaking the download when the shader was updated.

Open Source

The launcher is open source. Everybody can review the source code here. This guarantees that no one can add malicious code or spy functionalities without other people getting aware of it.