Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a Utilities page to the docs, along with some sections on installing for mac #17

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added assets/DevTools_stringIDs.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/EditorCollab_tags.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
24 changes: 21 additions & 3 deletions geode/cli-to-path.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Adding CLI to PATH

> :warning: Note: this section is for Windows only.

In order for the CLI to be accessible from anywhere on your computer, it needs to be added to your `PATH` environment variable. If you know what that means, you know how to do it; otherwise, follow these steps:

## On Windows

1. Select the CLI executable in File Explorer, Shift + Right-Click it and select `Copy as Path`

2. Search `Edit the system environment variables` on Windows search. Alternatively, you can open up Control Panel and search for it, then select `Edit the system environment variables` or **to skip straight to step 3 select `Edit environment variables for your account`**.
Expand All @@ -16,10 +16,28 @@ In order for the CLI to be accessible from anywhere on your computer, it needs t

6. Click OK to close the environment variable windows.

## Making sure it works
### Making sure it works

1. Open up Windows search and open `cmd` or `powershell`

2. Type `geode` and hit Enter. If CLI was installed correctly, you should see the CLI help displaying its version and commands.

If the command didn't work, try restarting the terminal you have open, or restarting your computer.

## On Mac

1. While holding down Control on your keyboard, Select the CLI executable in the Finder app.

2. While holding down Option/Alt on your keyboard, click `Copy "geode" as Pathname`

3. Now press Command + Spacebar to open the MacOS search, type `Terminal`, and press Enter. This should bring up the Terminal application in a new window.

4. In the Terminal window, write `export PATH="my/path/to/folder:${PATH}"` replacing `my/path/to/folder` with the path of the CLI executable you copied at Step 2. **Remove the `\geode` from the end;** the path has to point to the _directory_ with Geode CLI, not the CLI itself.

5. Press Enter on your keyboard to execute the command.

### Making sure it works

1. On that same Terminal window, type `geode` and hit Enter. If CLI was installed correctly, you should see the CLI help displaying its version and commands.

If the command didn't work, try restarting the terminal you have open, or restarting your computer.
16 changes: 15 additions & 1 deletion mods/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,15 +68,26 @@ A 64-bit integer value. Value may be limited with the `min`, `max`, and `one-of`

In code, the value type is `int64_t`.

Inside the `control` property, you can also set:
* `arrows`: Whether to show the arrow buttons or not
* `arrow-step`: How much to step when clicking the arrow buttons
* `big-arrows`: Whether to add bigger arrows that step further than the regular ones
* `big-arrow-step`: How much to step when clicking the big arrows
* `slider-step`: How much to step per slider interval
* `input`: Whether to allow a text input along with the slider

### `float`

A 64-bit floating point (decimal) value. Value may be limited with the `min`, `max`, and `one-of` properties. Available controls include a slider, arrows (buttons that increment/decrement by a predetermined amount), and a text input.

In code, the value type is `double`.

Inside the `control` property, you can also set:
* `slider-step`: How much to step per slider interval

### `string`

A piece of text. Value may be constrained with the `regex` key that specifies a regex that the string is matched against.
A piece of text. Value may be constrained with the `match` key that specifies a regex that the string is matched against.

In code, the value type is `std::string`.

Expand All @@ -96,6 +107,9 @@ In code, the value type is `ccColor4b`.

A file input, useful for example for configuration files. Controls include what file extension filters to show in the in-game file picker.

Inside the `control` property, you can also set:
* `filters`: Filter what file extensions can be submitted

### `custom`

A custom setting; see the next section for more info.
Expand Down
19 changes: 19 additions & 0 deletions mods/tags.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Tags

To help people find and download your Geode mod on the in-game Download tab, it has to be easily findable through a category or certain type of mods. Well, worry no more because this can be done through the Tags system! Using this system, you can add keywords to your mod listing, and it can be found using Geode's search filters.

While you can make your own tag by writing a new keyword in the tags of your mod, it is highly recommended that you use an already established tag to prevent unnecessary tags being added, and to allow for a more organized Search Filters page.

## Add Tags to your mod

In your mod listing's `entry.json`, you should add a section like this:
```json
"tags": [
"Player",
"Editor",
"Online"
]
```

Once your mod is approved and added to the index, the listing should look something like this:
![Image showing the Editor Collab mod and its tags](/assets/EditorCollab_tags.png)
4 changes: 3 additions & 1 deletion tutorials/nodetree.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,16 @@ Notice that there are no hardcoded indexes. Even if `main-menu` is at a complete

Although, this code does also have another interoperability concern: sure, we can be sure we added our node to the right place, but what if some other mod does the same? If another mod adds a button to the left of the icon kit button, they would overlap. To solve this issue, Geode introduces [layouts](/tutorials/layouts.md), which are discussed in their own tutorial.

This also highlights the **problem with string IDs**: **someone has to assign them**. Whereas raw indexes are an intrinsic property of all CCNodes, the default ID of a node is an empty string (`""`). Geode does come with [default IDs for common classes like `MenuLayer`](https://github.com/geode-sdk/geode/blob/91cecf3843d246939be4057cdf8e7d5d607aeeb1/loader/src/hooks/MenuLayer.cpp#L150-L197), but there are unfortunately too many layers in GD to label all of them.
This also highlights the **problem with string IDs**: **someone has to assign them**. Whereas raw indexes are an intrinsic property of all CCNodes, the default ID of a node is an empty string (`""`). Geode fortunately comes with [IDs for most classes in GD](https://github.com/geode-sdk/geode/tree/main/loader/src/ids). It is worth noting that there are unfortunately too many layers in GD to label all of them, so it may be missing some of them.

This has, however, been taken in mind when designing the string ID system. If you find a layer you want to get a child of is missing string IDs, what you can do is **add them yourself** (using members or raw indexes), and either [send your code for adding them to Geode](https://github.com/geode-sdk/geode/pulls/new) or [let others know your mod adds these IDs](https://discord.gg/9e43WMKzhp). This way, someone else who wants to get the same children from the same layer can easily piggyback off of your logic. While the string ID system is ultimately and unfortunately based on raw indexes, its point is to **provide a single source of truth for those indexes**; once someone has done the work, no one should have to do it again.

## Viewing String IDs

You can see if a layer's nodes have string IDs using the [DevTools](https://github.com/geode-sdk/devtools) mod, which shows them in the **Tree** view.

![Image showing the node string IDs, visible from the DevTools mod](/assets/DevTools_stringIDs.png)

## String IDs in your own layers

It is recommended for you to also use string IDs in your own layers, as this makes mod-modifying-mod interoperability much easier.
Expand Down
157 changes: 157 additions & 0 deletions tutorials/utils.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
# Utils

Along with Geode's many features and luxuries that make modding the game itself much easier, Geode also comes with tons of utilities to make some basic tasks alot easier to do in a Geode mod. These should **always** be preferred against any other method that could be platform specific.

> :info: This list does not cover absolutely all of the utilities that Geode has to offer. You can see all of them in [the repository](https://github.com/geode-sdk/geode/tree/main/loader/include/Geode/utils).

## General Utilities

### `strfmt`

Formats a `std::string`

### `cstrfmt`

Formats a `char const*`

### `intToHex`

Simply converts a number to hex in `std::string`

### `numToString`

Turn a number into a string, with support for specifying precision (unlike `std::to_string`).

### `timePointToString`

Converts a `std::chrono::system_clock::time_point` to a `std::string`

## File Utilities

### `readString`

### `readJson`

### `readBinary`

### `createDirectory`

### `readDirectory`

## Cocos Utilities

### `calculateNodeCoverage`

Get bounds for a set of nodes. Based on content size.

### `switchToScene`

Create a CCScene from a layer and switch to it with the default fade transition.

### `reloadTextures`

Reload textures, overwriting the scene to return to after the loading screen is finished.

### `limitNodeSize`

Rescale node to fit inside given size.

### `nodeIsVisible`

Checks if a node is visible (recursively checks parent visibility).

### `getChildByTagRecursive`

Gets a node by tag by traversing children recursively.

### `findFirstChildRecursive`

Get first node that conforms to the predicate by traversing children recursively.

> :warning: Both `getChildByTagRecursive` and `findFirstChildRecursive` should **never** be the primary way to find nodes. Always prioritize using Geode's [string ID system](/tutorials/nodetree.md#string-ids) to find nodes.

### `fileExistsInSearchPaths`

Checks if a given file exists in CCFileUtils search paths.

### `invert4B`

Inverts a `ccColor4B` color.

### `invert3B`

Inverts a `ccColor3B` color.

### `lighten3B`

Lightens a `ccColor3B`'s color by a certain amount

### `darkenB`

Darkens a `ccColor3B`'s color by a certain amount

### `to3B`

Converts a `ccColor4B` to a `ccColor3B`

### `to4B`

Converts a `ccColor3B` to a `ccColor4B` (with support for choosing the alpha)

### `to4F`

Converts a `ccColor4B` to a `ccColor4F`

### `cc3x`

Converts a number hex value to a `ccColor3B`

### `cc3bFromHexString`

Converts a `ccColor3B` to a hex `std::string`

### `cc4bFromHexString`

Converts a `ccColor4B` to a hex `std::string`

### `cc3bToHexString`

Converts a hex `std::string` to a `ccColor3B`

### `cc4bToHexString`

Converts a hex `std::string` to a `ccColor4B`

## `vectorToCCArray`

Converts a `std::vector` of any type to a `CCArray`

## `ccArrayToVector`

Converts a `CCArray` to a `std::vector`

## `mapToCCDict`

Converts a `std::map` to a `CCDictionary`

## `getMousePos`

Gets the mouse position in cocos2d coordinates. On mobile platforms, this will return (0, 0)

## Web Utilities

### `openLinkInBrowser`

A simple way to open a link in the user's browser.

### `fetch`

Fetches data from a URL and returns it as a `std::string`.

### `fetchFile`

Fetches data as a file from a URL and uses a `ghc::filesystem::path` as a path for the file.

### `fetchJSON`

Fetches data from a URL and parses it as a `JSON::value`