|
1 | | -# Configuring Chunky Launcher |
| 1 | +# Configuring the Chunky Launcher |
2 | 2 |
|
3 | | ---- |
| 3 | +Before being able to render scenes, some actions must be performed in the Chunky Launcher. |
4 | 4 |
|
5 | | -The Chunky Launcher contains controls that are set before launching Chunky. |
6 | | - |
7 | | -<div class="figure" id="figure-1-2-1"> |
8 | | - <p class="figure"> |
9 | | - Figure 1.2.1: The Chunky Launcher |
10 | | - </p> |
| 5 | +<div class="figure" id="figure-1"> |
| 6 | + <p class="figure">Figure 1: The Chunky Launcher</p> |
11 | 7 | <div class="figureimgcontainer"> |
12 | | - <a href="../../img/getting_started/chunky_launcher.png"> |
13 | | - <img class="figure" src="../../img/getting_started/chunky_launcher.png" alt="The Chunky Launcher"> |
| 8 | + <a href="../../img/reference/user_interface/chunky_launcher/chunky_launcher_gui/chunky_launcher.png"> |
| 9 | + <img class="figure" src="../../img/reference/user_interface/chunky_launcher/chunky_launcher_gui/chunky_launcher.png" alt="Chunky Launcher"> |
14 | 10 | </a> |
15 | 11 | </div> |
16 | 12 | </div> |
17 | 13 |
|
18 | | ---- |
19 | | - |
20 | | -## Controls |
21 | | - |
22 | | -- `Version select`: Drop down list which allows you to select a downloaded Chunky version to launch. |
23 | | - |
24 | | -- `Check for update`: Checks for updates on chosen update site. |
25 | | - |
26 | | -- `Minecraft directory`: Displays the path to the directory to which Minecraft is installed. It can be changed by clicking the `...` button immediately to the right of the text box. |
27 | | - |
28 | | -- `Memory limit (MiB)`: Changes the amount of RAM that is allocated to Chunky. The default is 1024 MiB; however, it is highly recommended that you raise this value to better reflect the amount of memory in your system. Please take into account that the operating system and other applications will also require some memory, so don't over-set this. If Chunky fails to launch if this is raised past 2000 MiB, double-check that your Java installation is 64-bit. |
29 | | - |
30 | | -- `Always open Launcher`: Changes whether the Launcher is shown when starting Chunky. If it becomes disabled, it is possible to access the launcher again via the command line or an [option in Chunky](../../reference/user_interface/right_panel_controls/options#controls). This is slightly more complicated, however, so it is recommended to keep this option enabled. |
| 14 | +## Updating Chunky |
31 | 15 |
|
32 | | -- `Cancel`: Closes the Chunky Launcher. |
| 16 | +If you downloaded the Chunky Launcher (Universal JAR), and this is your first time starting Chunky, then you must update Chunky. Otherwise, click <samp>Launch</samp> to start Chunky. |
33 | 17 |
|
34 | | -- `Launch`: Attempts to launch the selected version of Chunky with the options set in the Launcher. |
| 18 | +In the Launcher, click the <samp>Check for update</samp> button to make the Launcher check for an update for Chunky online. If an update to Chunky is available, you will soon see the 'Update Available' window: |
35 | 19 |
|
36 | | ---- |
37 | | - |
38 | | -### Advanced Settings |
39 | | - |
40 | | -<div class="figure" id="figure-1-2-2"> |
41 | | - <p class="figure"> |
42 | | - Figure 1.2.2: Chunky Launcher Advanced Settings |
43 | | - </p> |
| 20 | +<div class="figure" id="figure-2"> |
| 21 | + <p class="figure">Figure 2: Chunky 'Update Available' Window</p> |
44 | 22 | <div class="figureimgcontainer"> |
45 | | - <a href="../../img/getting_started/chunky_launcher_advanced.png"> |
46 | | - <img class="figure" src="../../img/getting_started/chunky_launcher_advanced.png" alt="Chunky Launcher Advanced Settings"> |
| 23 | + <a href="../../img/getting_started/configuring_chunky_launcher/chunky_update_available.png"> |
| 24 | + <img class="figure" src="../../img/getting_started/configuring_chunky_launcher/chunky_update_available.png" alt="Chunky Update Available Window"> |
47 | 25 | </a> |
48 | 26 | </div> |
49 | 27 | </div> |
50 | 28 |
|
51 | | -- `Update Site`: Input field for the source of Chunky updates. |
52 | | - |
53 | | - - `https://chunkyupdate.llbit.se/`: This should be used to obtain Chunky 1.X, which supports worlds saved in Minecraft versions up to 1.12.2. |
54 | | - |
55 | | - - `https://chunkyupdate2.llbit.se/`: This is for llbit's Chunky 2.0 for Minecraft 1.13. To obtain the latest version, which is `2.0beta6`, you must set the `Release channel` to `Snapshot`. Otherwise, you will be stuck with an older version. |
56 | | - |
57 | | - - `https://chunkyupdate.lemaik.de/`: This is the new default update site used to obtain Chunky 2.x. |
58 | | - |
59 | | - - `https://chunky-pr.lemaik.de/`: This update site is used to download builds of open pull requests. Click `Reload` next to the `Release channel` dropdown menu and then set the `Release Channel` to `PR #xxxx`, with "xxxx" being the number of the open pull request. For more information, read <a href="https://github.com/leMaik/chunky-pr-as-update-site/blob/master/README.md" target="_blank">this page</a>. |
60 | | - |
61 | | -- `Reset`: Resets the `Update Site` to the default of `https://chunkyupdate.lemaik.de`. |
62 | | - |
63 | | -- `Java Runtime`: Displays the path of the runtime used for Chunky. It can be changed by clicking the `...` button immediately to the right of the text box. It does not change the runtime used for the Launcher. |
64 | | - |
65 | | -- `Java options`: Input field for Java options that will be set for Chunky upon launch. See [below](#java-options) for the list of Java options. |
66 | | - |
67 | | -- `Chunky options`: Input field for options specific to Chunky that will be set upon launch. See [below](#chunky-options) for the list of Chunky options. |
68 | | - |
69 | | -- `Enable debug console`: Enables the debug console, which is a separate window that opens when Chunky is launched. The debug console logs information that is useful for debugging issues with Chunky. |
70 | | - |
71 | | -- `Verbose logging`: Enables additional information to be logged in the debug console to further help fix issues. |
72 | | - |
73 | | -- `Close console when Chunky exits`: Changes whether the debug console will close when Chunky exits normally. Typically, this can be left enabled. If an exception or error causes Chunky to crash and exit abnormally, the debug console will remain open and readable. |
74 | | - |
75 | | -- `Release channel`: Sets the release channel used by the Launcher when checking for updates. The different release channels set the type of release that Chunky attempts to download when checking for updates. |
76 | | - |
77 | | - - `Stable`: Downloads stable releases of Chunky, which generally have fewer bugs than Stable Snapshot releases or Snapshot releases do. |
78 | | - |
79 | | - - `Stable Snapshot`: Downloads stable snapshot builds of Chunky from the <a href="https://github.com/chunky-dev/chunky/tree/chunky-2.4.x" target="_blank">chunky-2.4.x</a> branch. Generally, these releases may contain new features, bug fixes, and potentially more bugs, but are considered more stable than Snapshot releases. |
80 | | - |
81 | | - - `Snapshot`: Downloads snapshot builds of Chunky from the <a href="https://github.com/chunky-dev/chunky/tree/master" target="_blank">master</a> branch. These releases contain the latest bug fixes and new features, but potentially the most new bugs. |
82 | | - |
83 | | - - `PR #xxxx`: Downloads the latest build of the open pull request, "xxxx" being the number of which, if the update site is set to `https://chunky-pr.lemaik.de/`. |
| 29 | +Click the <samp>Update to New Version</samp> button to start downloading the required files. |
| 30 | +When the download process has completed, you can click on either <samp>Launch Chunky</samp> or <samp>Close</samp>. If you click on <samp>Close</samp>, you would need to click on <samp>Launch</samp> in the main Chunky Launcher window to launch Chunky. |
84 | 31 |
|
85 | | -- `Settings directory`: Displays the path of the Chunky settings directory. |
86 | | - |
87 | | -- `Open`: Opens the Chunky settings directory. |
88 | | - |
89 | | -- `Manage plugins`: Opens the [`Plugin Manager`](#plugin-manager) dialog box, which is used to manage installed [plugins](../../plugins/chunky_plugins). |
90 | | - |
91 | | ---- |
92 | | - |
93 | | -### Java options |
94 | | - |
95 | | -Separate Java options from each other with a space. |
96 | | - |
97 | | -- `-Dprism.order=sw`: Add this if the Chunky Launcher or the Chunky window appear blank when started. This is caused by an issue with the JavaFX hardware renderer for Windows. The only known solution is to add the listed Java command/option. This may reduce responsiveness compared to `hw`/`d3d`, but that mode is limited by the maximum texture size of your GPU drivers. Use `-Dprism.verbose=true` to list available pipelines in the debug console. |
98 | | - |
99 | | -- `-Dprism.maxvram=512M`: The texture cache defaults to `512M`. Raising this value can allow you to render at a resolution closer to the maximum texture size allowed in hardware modes and can also help resolve issues with the software mode. You can allocate using `M` or `G` suffixes. `1024M` = `1G`. |
100 | | - |
101 | | -- `-DlogLevel=INFO`: `ERROR`, `WARNING`, `INFO` - The default is `WARNING`, which will mean that Chunky will show warnings for missing items. Switching to `ERROR` should disable missing item warnings. |
102 | | - |
103 | | -Work-in-progress <a href="https://github.com/leMaik/chunky/tree/pbr" target="_blank">PBR builds of Chunky</a> have additional options required. These options may be added to the UI at a later time. |
104 | | - |
105 | | -- `-Dchunky.pbr.specular=labpbr`: `labpbr`, `oldpbr` - Tells Chunky which format the specular map is in. |
106 | | - |
107 | | -- `-Dchunky.pbr.updateMaterialDefaults=true`: Sets default material properties to `Emittance`: 1, `Smoothness`: 1, and `Metalness`: 1 such that the specular map is applied to all materials. |
108 | | - |
109 | | -- `-Dchunky.pbr.normal=true`: Enables normal mapping on certain blocks (cubes with the same texture on each face), such as planks, cobblestone, stone bricks, etc. |
110 | | - |
111 | | ---- |
112 | | - |
113 | | -### Chunky options |
114 | | - |
115 | | -- `-tile-width <NUM>`: Modifies the frame subdivision size per worker thread. Can potentially provide a boost to render speed or, if set too high, reduce render speeds. It is recommended to use a tile-width of 16 as this seems to be optimal, though you may want to test your system in a typical workload to see what works better. |
116 | | - |
117 | | -- `-spp-per-pass <NUM>`: The spp-per-pass defines the number of samples a certain tile should be rendered to before moving on to the next tile. The default value of *1* means that each pixel will be sampled once per pass. This results in the render preview displaying the most recent render progress, and responding to changes after only one pass is rendered. Raising the spp-per-pass breaks some of the GUI functionality; however, rendering performance may be improved. It is recommended that this option be only used for headless operation. |
118 | | - |
119 | | ---- |
120 | | - |
121 | | -### Plugin Manager |
122 | | - |
123 | | -The `Plugin Manager` dialog box, shown in [Figure 1.2.3](#figure-1-2-3), displays a list of all detected plugins, along with some management controls. |
124 | | - |
125 | | -<div class="figure" id="figure-1-2-3"> |
126 | | - <p class="figure"> |
127 | | - Figure 1.2.3: Plugin Manager dialog box |
128 | | - </p> |
129 | | - <div class="figureimgcontainer"> |
130 | | - <a href="../../img/getting_started/chunky_launcher_plugin_manager.png"> |
131 | | - <img class="figure" src="../../img/getting_started/chunky_launcher_plugin_manager.png" alt="Plugins Manager dialog box"> |
132 | | - </a> |
133 | | - </div> |
134 | | -</div> |
| 32 | +## Optional Configuration |
135 | 33 |
|
136 | | -The `Plugin manager` dialog box will display any plugins from the "plugins" directory of the Chunky [settings directory](#controls). The column headers can be clicked to reorder the plugins by any listed detail. A plugin in the list can be clicked to select it. The checkbox on a plugin entry can be checked to select that plugin to be loaded when Chunky is launched. |
| 34 | +- <samp>Minecraft directory</samp>: If your Minecraft game directory (.minecraft) is located somewhere other than its default location, then you may also need to change this to point to your current Minecraft installation; otherwise, blocks rendered in Chunky will not have proper textures, and your worlds will not be found. |
137 | 35 |
|
138 | | -- `Plugin Details`: Collapsible panel that contains information about the selected plugin. |
| 36 | +- <samp>Memory limit (MiB)</samp>: Chunky can use much memory depending on a number of factors. Many issues can be caused by Chunky not having enough memory, so raising the memory limit can solve these issues. The default of *1024* can be raised based upon how much memory your system has and how much is typically available. For example, if your system has 16 GiB (16384 MiB) of system memory, allocating up to 75% of that, which is 12 GiB (12288 MiB), is typically fine. You can allocate more; however, you may eventually encounter other problems. |
139 | 37 |
|
140 | | -- `Up`: Moves the selected plugin above the plugin that is immediately above it. |
| 38 | +You should not need to access [<samp>Advanced Settings</samp>](../../reference/user_interface/chunky_launcher/chunky_launcher_gui#advanced-settings). |
141 | 39 |
|
142 | | -- `Down`: Moves the selected plugin below the plugin that is immediately below it. |
| 40 | +## Troubleshooting |
143 | 41 |
|
144 | | -- `Delete`: Deletes the plugin from the "plugins" directory, thereby removing it from the list. |
| 42 | +If the Launcher does not download the latest version or new snapshots, check the <samp>Update Site</samp> in the <samp>Advanced Settings</samp> panel. The URL changed with Chunky 2.1, so make sure it is set to `https://chunkyupdate.lemaik.de/`. If you have used Chunky 1.x, it may still be set to llbit's update site. You can keep using that if you want to use Chunky 1.4.5.[^1] |
145 | 43 |
|
146 | | -- `Add`: Opens a file explorer dialog box to browse for a JAR file to be added to the "plugins" directory. |
| 44 | +If you get an unchecked exception caused by `java.lang.NoClassDefFoundError: javafx/application/Application` when clicking <samp>Launch</samp> in the Chunky Launcher, then double-check that the <samp>Java Options</samp> input field under <samp>Advanced Settings</samp> is populated by `--module-path "<path\to\javafx\lib>" --add-modules javafx.controls,javafx.fxml`.[^2] [^3] This field is automatically populated if the Chunky Launcher automatically detects OpenJFX. If OpenJFX is added manually in the startup command, then the field must be populated manually. |
147 | 45 |
|
148 | | -- `Open plugin directory`: Opens the "plugins" directory of the Chunky [settings directory](#controls). |
| 46 | +[^1]: Chunky 2.4.0 supports Minecraft 1.2.1 and above (i.e., pre-flattening worlds), so you probably do not need the old version anymore. |
149 | 47 |
|
150 | | -- `Save`: Saves the new plugin configuration and closes the `Plugin Manager` dialog box. |
| 48 | +[^2]: It is important that quotation marks `" "` be included around any file paths to ensure that special characters like hyphens `-`, spaces ` `, etc., do not cause issues. |
151 | 49 |
|
152 | | ---- |
| 50 | +[^3]: Replace text within angle brackets `< >` with the actual paths to the files on your computer, and do not include the angle brackets in the actual command or input. |
153 | 51 |
|
154 | 52 | --8<-- "includes/abbreviations.md" |
0 commit comments