Expanded documentation

.vitepress/config.js

@@ -22,10 +22,21 @@ module.exports = {
     sidebar: {
       "/guide/": [
         {
-          text: "Guide",
+          text: "Getting Started",
           children: [
             { text: "Introduction", link: "/guide/" },
-            { text: "Getting Started", link: "/guide/getting-started" }
+            { text: "Setting Up", link: "/guide/setup" },
+            { text: "Updating Profectus", link: "/guide/updating" }
+          ]
+        },
+        {
+          text: "Creating Your Project",
+          children: [
+            { text: "Project Info", link: "/guide/project-info" },
+            { text: "Project Entry", link: "/guide/project-entry" },
+            { text: "Layers", link: "/guide/layers" },
+            { text: "Changelog", link: "/guide/changelog" },
+            { text: "Themes", link: "/guide/themes" }
           ]
         },
         {

.vitepress/theme/custom.css

@@ -6,3 +6,7 @@
 .custom-block.info {
 	background-color: #3B4252;
 }
+
+.custom-block.warning {
+	background-color: #EBCB8B;
+}

guide/changelog.md

@@ -0,0 +1,22 @@
+# Changelog
+
+This is a Vue component stored at `/src/data/Changelog.vue` used to display all the changes version to version. You can use any features you'd like within here, but it's recommended to simply add new `<details>` elements for each new major release, and mark the most recent one as `open` by default. It is strongly advised to not change any of the code relating to making the changelog appear in a modal.
+
+There is a single version included by default that can serve as a reference of how it is recommended to add a version to the changelog:
+
+```html
+<details open>
+	<summary>v0.0 Initial Commit - <time>2021-09-04</time></summary>
+	This is the first release :D
+	<ul>
+		<li class="feature">Did everything</li>
+		<li class="fix">Had some fun</li>
+		<li class="breaking">Removed everything</li>
+		<li class="balancing">Created some bugs to fix later</li>
+	</ul>
+</details>
+```
+
+The `details` and `summary` tags will create a section that can be collapsed and uncollapsed. While collapsed only the text in the `summary` tag will appear. By default sections are collapsed, although adding the `open` attribute to the `details` element will change that. 
+
+Within the details of the version, you can add a description and a list of changes for that version. CSS classes have been defined to automatically mark a change as a feature, fix, breaking change, or balancing tweak. You can of course add additional tags as you have full control over the entire component.

guide/layers.md

@@ -0,0 +1,7 @@
+# Layers
+
+Profectus content is organized into units called "Layers". When display content to the user, it will be done so by having some number of layers appearing as sections on the screen. They are stored in `/src/data/layers`.
+
+Each layer is ultimately a collection of different features, and a display function. While there are a couple reserved properties for layers, most of its structure is fully up to the creator. 
+
+Layers can be dynamically added or removed at any time, which also allows for effectively disabling or enabling content based on arbitrary conditions. Just make sure [getInitialLayers](./projEntry.md#getInitialLayers) can process the player save data object and determine which layers should be currently active. 

guide/project-entry.md

@@ -0,0 +1,34 @@
+# Project Entry
+
+This is a TypeScript file containing the non-static parts of your project, and acts as the entry point for it.
+
+It is stored at `/src/data/projEntry.jsx`.
+
+This file has 3 things it must export, but beyond that can export anything the creator wants it to. Typically in addition to the required 3, the initial/"main" layer will be exported. Typically utilites belong in `common.tsx`, which exists next to `projEntry.tsx`. 
+
+## Required Exports
+
+### getInitialLayers
+
+- Type: `(player: Partial<PlayerData>) => GenericLayer[]`
+
+A function that is given a player save data object currently being loaded, and returns a list of layers that should be active for that player. If a project does not have dynamic layers, this should always return a list of all layers. 
+
+### hasWon
+
+- Type: `ComputedRef<boolean>`
+
+A computed ref whose value is true whenever the game is over. 
+
+For example, in a game where the goal is to have a resource reach 10:
+```ts
+export const hasWon = computed(() => Decimal.gte(resource.value, 10));
+```
+
+### fixOldSave
+
+- Type: `(oldVersion: string | undefined, player: Partial<PlayerData>) => void`
+
+This function will be run whenever a save is loaded that has a different version than the one in [project info](./project-info.md#versionnumber). It will be given the old version number, and the player save data object currently being loaded.
+
+The purpose of this function is to perform any necessary migrations, such as capping a resource that accidentally inflated in a previous version of the project. By default it will do nothing.

guide/project-info.md

@@ -0,0 +1,131 @@
+# Project Info
+
+This is a JSON file containing information that describes your project and configures parts of how Profectus should represent it.
+
+It is stored at `/src/data/projInfo.json`.
+
+## Basic Config
+
+### title
+
+- Type: `string`
+- Default: `Profectus`
+
+The name of the project, which will appear in the info tab and in the header, if enabled. The page title will also be set to this value.
+
+### id
+
+- Type: `string`
+- Default: `""`
+
+This is a unique ID used when saving player data. Changing this will effectively erase all save data for all players.
+
+::: warning
+This ID MUST be unique to your project, and should not be left as the default value. Otherwise your project may use the save data from another project and cause issues for both projects.
+:::
+
+### author
+
+- Type: `string`
+- Default: `""`
+
+The author of the project, which will appear in the info tab.
+
+### discordName
+
+- Type: `string`
+- Default: `The Paper Pilot Community`
+
+The text to display for the discord server to point user's to. This will appear when hovering over the discord icon, inside the info tab, the game over screen, as well as the NaN detected screen.
+
+By default, this is The Paper Pilot Community, which can act as a catch-all for any Profectus projects without their own servers. If you change the discord server with your own, The Paper Pilot Community will still display underneath the custom server when hovering over the discord icon and within the info tab. Those places will also contain a link to the Modding Tree discord server.
+
+### discordLink
+
+- Type: `string`
+- Default: `https://discord.gg/WzejVAx`
+
+The link for the discord server to point user's to. See [discordName](#discordname) for more details.
+
+## Version Config
+
+### versionNumber
+
+- Type: `string`
+- Default: `0.0`
+
+The current version of the project loaded. If the player data was last saved in a different version of the project, [fixOldSave](./project-entry.md#fixoldsave) will be run, so you can perform any save migrations necessary. This will also appear in the nav, the info tab, and the game over screen.
+
+### versionTitle
+
+- Type: `string`
+- Default: `Initial Commit`
+
+The display name for the current version of the project loaded. This will also appear in the nav, the info tab, and the game over screen, unless set to an empty string.
+
+## Display Config
+
+### allowGoBack
+
+- Type: `boolean`
+- Default: `true`
+
+Whether or not to allow tabs (besides the first) to display a "back" button to close them (and any other tabs to the right of them).
+
+### defaultShowSmall
+
+- Type: `boolean`
+- Default: `false`
+
+Whether or not to allow resources to display small values (<.001). If false they'll just display as 0. Individual resources can also be configured to override this value.
+
+### defaultDecimalsShown
+
+- Type: `number`
+- Default: `2`
+
+Default precision to display numbers at when passed into `format`. Individual `format` calls can override this value, and resources can be configured with a custom precision as well.
+
+### useHeader
+
+- Type: `boolean`
+- Default: `true`
+
+Whether or not to display the nav as a header at the top of the screen. If disabled, the nav will appear on the left side of the screen laid over the first tab. 
+
+### banner
+
+- Type: `string | null`
+- Default: `null`
+
+A path to an image file to display as the logo of the app. If null, the title will be shown instead. This will appear in the nav when `useHeader` is true.
+
+### logo
+
+- Type: `string`
+- Default: `""`
+
+A path to an image file to display as the logo of the app within the info tab. If left blank no logo will be shown.
+
+### initialTabs
+
+- Type: `string[]`
+- Default: `["main"]`
+
+The list of initial tabs to display on new saves. This value must have at least one element. Each element should be the ID of the layer to display in that tab. 
+
+## Advanced Config
+
+### maxTickLength
+
+- Type: `number`
+- Default: `3600`
+
+The longest duration a single tick can be, in seconds. When calculating things like offline time, a single tick will be forced to be this amount or lower. This will make calculating offline time spread out across many ticks as necessary. The default value is 1 hour.
+
+### offlineLimit
+
+- Type: `number`
+- Default: `1`
+
+The max amount of time that can be stored as offline time, in hours. 

guide/setup.md

@@ -1,21 +1,15 @@
-# Getting Started
+# Setting Up
 
-## Setting up environment
+Profectus requires a node development environment in order to work on a project. If you are comfortable with the command line, it is recommended to use a local development environment.
 
-#### Tools
+## Local Development
 
-Profectus requires a node development environment in order to work on a project. If you are familiar with node, then you can skip this section.
+You will require the following tools for local development:
-
-If you are comfortable with/willing to use the command line, it is recommended to download the following:
 
 - [git](https://git-scm.com/downloads)
 - [node](https://nodejs.org/en/download/)
 
-If you'd like, you can also choose to use [replit](https://replit.com) or [glitch](https://glitch.com), which has several pros and cons, but one of the pros is not needing to setup any tool on your own computer.
+Create a new project from the [Profectus repository](https://github.com/profectus-engine/Profectus) via the "Use this template" button. You can then copy the link for the repository to clone it locally.
-
-#### Creating your project
-
-If you are using git, you should create a new project from the [Profectus repository](https://github.com/profectus-engine/Profectus) via the "Use this template" button. You can then copy the link for the repository to clone it locally.
 
 ::: info
 Since the repository is a template repository, you can easily create multiple projects from one repository. However, it does make updating an existing project to a newer version of Profectus more difficult.
@@ -25,23 +19,9 @@ It's recommended to create a new git branch for development, so you can push you
 
 The next step is to install Profectus' dependencies. This is as simple as running `npm install`.
 
-#### Running your project
-
 You can now run `npm serve` to start a local server that will host your project so you can work on it. As you change files the site will automatically reload them.
 
-## Project structure
+### Deploying
-
-At least to start, everything you'll be messing with is inside the `/src/data` directory. This contains everything specific to the project itself, from its metadata, the content itself, utility functions, a changelog, and any custom UI themes.
-
-#### Setting up project metadata
-
-The first file you'll want to edit is `/src/data/modInfo.json`. This contains information on the name of the project, its creator, a discord server to link to, and some other general information about the project.
-
-#### Creating your project
-
-Being actually creating your project content by editing `mod.tsx`.
-
-## Deploying
 
 If you're using git, deploying is as easy as pushing your changes to the `main` branch. In a couple minutes the site will be updated fully automatically. If you'd like to see progress on it, or look at any errors that happened, you can do so from the actions tab on your repository.
 
@@ -52,3 +32,19 @@ Before github knows to actually host the generated site, you'll have to enable g
 ![github pages](./gh-pages.png)
 
 Once the action completes, your project should be available at `https://<YOUR_GITHUB_USERNAME>.github.io/<YOUR_REPO_NAME>/`. For example, the TMT Demo project hosted at https://github.com/profectus-engine/TMT-Demo is available at https://profectus-engine.github.io/TMT-Demo/.
+
+## Replit
+
+As an alternative to local development, you may use [replit](https://replit.com), which will automatically set up your development environment for you and also host your project itself.
+
+However, on the free plan you will be limited by the amount of resources you can use, and the program will need to start up occasionally.
+
+To create a Profectus project on replit, all you have to do is click this button:
+
+[![Run on Repl.it](https://repl.it/badge/github/profectus-engine/Profectus)](https://repl.it/github/profectus-engine/Profectus)
+
+You can then start the developing by clicking the "Run" button at the top of the screen. This will also make the project run publicly, so you could consider it as automatically deployed. This does mean you cannot have a separate development environment from your production environment, however.
+
+## Glitch
+
+[Glitch](https://glitch.com) is a site similar to replit, with much the same pros and cons. To create a projectus project on glitch, select "New Project", "Import from GitHub", and then type in `profectus-engine/Profectus`. The new project will be created and should be automatically configured and ready to go.

guide/themes.md

@@ -0,0 +1,29 @@
+# Themes
+
+Themes are objects that change how the project's interface should look. This is done mostly by changing the values of various CSS variables. You can look at the existing themes as a reference for the kind of values these CSS variables expect. They can also set various theme options that change how parts of the screen are laid out, which are described [below](#theme-options).
+
+They are stored in `/src/data/themes.ts`.
+
+## Modifying Themes
+
+You can add a theme by adding a property to the `Themes` enum and then including the theme in the exported object. It's recommended to use the spread operator if you'd like to have a theme look like another, but override specific options / CSS variables.
+
+Themes added in this way will be automatically included in the Themes dropdown in the Options tab. Removing themes from the enum and exported object will similarly hide them from the dropdown.
+
+If you'd like to change which theme is the default, you may modify the initial player settings object in the `/src/game/settings.ts` file. Keep in mind you'll also want to change it in the `hardResetSettings` function in the same file.
+
+## Theme Options
+
+### floatingTabs
+
+- Type: `boolean`
+
+Toggles whether to display tab buttons in a tab list, similar to how a browser displays tabs; or to display them as floating buttons, similar to how TMT displays buttons.
+
+### mergeAdjacent
+
+- Type: `boolean`
+
+If true, elements in a row or column will have their margins removed and border radiuses set to 0 between elements. This will cause the elements to appear as segments in a single object. 
+
+Currently, this can only merge in a single dimension. Rows of columns or columns of rows will not merge into a single rectangular object.

guide/updating.md

@@ -0,0 +1,21 @@
+# Updating Profectus
+
+## Github
+
+Due to Profectus being a template repository, your projects do not share a git history with Profectus. In order to update changes, you will need to run the following:
+
+```bash
+git remote add template https://github.com/profectus-engine/Profectus
+git fetch --all
+git merge template/main --allow-unrelated-histories
+```
+
+The first command only has to be performed once. The third command may require you to merge conflicts between code both you and Profectus have changed - however, due to the modularity of Profectus, this should be fairly rare. Unfortunately, due to the unrelated histories the first time you do this _every_ change will be marked as a conflict, and you'll need to accept each one.
+
+## Replit
+
+The sidebar has a tab labelled "Version Control", which you can use to merge all changes made to Profectus into your project. Unfortunately, replit does not have a merge tool so this process may irrecoverably erase changes you've made - I'd recommend making a backup first.
+
+## Glitch
+
+Unfortunately glitch does not provide any method by which to update a project from a github repository. If you've only changed things in the data folder you may consider creating a new project, importing the current version of Profectus, and then placing your data folder in the new project.

index.md

@@ -4,7 +4,7 @@ title: Home
 heroText: Profectus
 tagline: A game engine that grows with you
 actionText: Get Started
-actionLink: /guide/getting-started
+actionLink: /guide/setup
 features:
     - title: Easy to Use
       details: Everything is written to be as intuitive to use as possible