mirror of
https://github.com/pesde-pkg/pesde.git
synced 2025-05-04 02:23:51 +01:00
docs: improve docs for publishing roblox packages
This commit is contained in:
LukaDev
parent
09820e322c
commit
c7a1b5328c
2 changed files with 205 additions and 5 deletions
|
|
@ -3,6 +3,8 @@ title: Publishing Packages
|
|||
description: Learn how to publish packages to the pesde registry.
|
||||
---
|
||||
|
||||
import { LinkCard } from "@astrojs/starlight/components"
|
||||
|
||||
## Configuration
|
||||
|
||||
Before you can publish a package, you must configure the required fields in your
|
||||
|
|
@ -41,15 +43,19 @@ lib = "init.luau"
|
|||
`build_files`. These are the files that should be synced into Roblox. They are
|
||||
passed to the `roblox_sync_config_generator` script.
|
||||
|
||||
For more information, see [Roblox](/guides/roblox).
|
||||
|
||||
```toml
|
||||
[target]
|
||||
environment = "roblox"
|
||||
lib = "init.luau"
|
||||
build_files = ["init.luau"]
|
||||
lib = "src/init.luau"
|
||||
build_files = ["src"]
|
||||
```
|
||||
|
||||
<LinkCard
|
||||
title="Roblox"
|
||||
description="Learn more about authoring packages for Roblox."
|
||||
href="/guides/roblox/#authoring-packages"
|
||||
/>
|
||||
|
||||
## Authentication
|
||||
|
||||
Before you can publish a package, you must authenticate with your GitHub account.
|
||||
|
|
|
|||
|
|
@ -3,6 +3,8 @@ title: Roblox
|
|||
description: Using pesde in a Roblox project.
|
||||
---
|
||||
|
||||
import { FileTree } from "@astrojs/starlight/components"
|
||||
|
||||
pesde can be used in Roblox projects, however this requires some extra setup.
|
||||
Namely, you need to specify a `roblox_sync_config_generator` script in order
|
||||
to generate the adequate configuration for the sync tool you are using.
|
||||
|
|
@ -29,8 +31,200 @@ needed to use pesde in a project using Rojo.
|
|||
If you are using a different sync tool, you should look for it's scripts in the
|
||||
pesde-scripts repository. If you cannot find them, you can write your own and
|
||||
optionally submit a PR to help others using the same tool as you get started
|
||||
quicker.
|
||||
quicker.
|
||||
|
||||
Scaffold your project with `pesde init`, select the `roblox` or `roblox_server`
|
||||
target, and then replace the `.pesde/roblox_sync_config_generator.luau` script
|
||||
with the one you want to use.
|
||||
|
||||
## Authoring packages
|
||||
|
||||
When authoring packages for Roblox, it is recommended to have your code inside
|
||||
of a `src` directory (or any other directory you prefer).
|
||||
|
||||
Inside of your `pesde.toml` you must specify the `roblox` environment and the
|
||||
`lib` field with the path to your main script. You must also specify a list of
|
||||
`build_files`. This list should contain names of top level files or directories
|
||||
that should be synced into Roblox by a sync tool, such as Rojo.
|
||||
|
||||
Let's say you have a package with the following structure:
|
||||
|
||||
<FileTree>
|
||||
|
||||
- roblox_packages/
|
||||
- dependency.luau
|
||||
- ...
|
||||
- src/
|
||||
- init.luau
|
||||
- foo.luau
|
||||
- bar.luau
|
||||
- ...
|
||||
- LICENSE
|
||||
- pesde.toml
|
||||
- README.md
|
||||
- selene.toml
|
||||
- stylua.toml
|
||||
|
||||
</FileTree>
|
||||
|
||||
There are lots of files in the root directory that are not needed in Roblox,
|
||||
such as configuration files, READMEs, and licenses. We only want the `src` and
|
||||
the `roblox_packages` directory to be synced into Roblox.
|
||||
|
||||
<FileTree>
|
||||
|
||||
- roblox_packages/
|
||||
- dependency (roblox_packages/dependency.luau)
|
||||
- ...
|
||||
- src/ (src/init.luau)
|
||||
- foo (src/foo.luau)
|
||||
- bar (src/bar.luau)
|
||||
- ...
|
||||
|
||||
</FileTree>
|
||||
|
||||
This is where `build_files` come in, we can specify a list of files that should
|
||||
be synced into Roblox. In this case, we only want the `src` directory to be
|
||||
synced. We do not need to specify the `roblox_packages` directory, as it is
|
||||
always synced.
|
||||
|
||||
So for our package, the `pesde.toml` file would roughly look like this:
|
||||
|
||||
```toml title="pesde.toml" {15}
|
||||
name = "acme/package"
|
||||
version = "1.0.0"
|
||||
license = "MIT"
|
||||
|
||||
includes = [
|
||||
"pesde.toml",
|
||||
"LICENSE",
|
||||
"README.md",
|
||||
"src",
|
||||
]
|
||||
|
||||
[target]
|
||||
environment = "roblox"
|
||||
lib = "src/init.luau"
|
||||
build_files = ["src"]
|
||||
|
||||
[dependencies]
|
||||
dependency = "acme/library"
|
||||
```
|
||||
|
||||
When a consumer of your package installs it, the `roblox_sync_config_generator`
|
||||
script they are using will generate the configuration needed for their sync
|
||||
tool. For example, a Rojo user would get a `default.project.json` with the
|
||||
following contents:
|
||||
|
||||
```json title="default.project.json"
|
||||
{
|
||||
"tree": {
|
||||
"src": {
|
||||
"$path": "src"
|
||||
},
|
||||
"roblox_packages": {
|
||||
"$path": "roblox_packages"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The linker scripts that pesde generates will then point to the `src` module.
|
||||
|
||||
Then, to publish your package, you can follow the steps in the
|
||||
["Publishing Packages"](/guides/publishing/) guide.
|
||||
|
||||
### Test place with Rojo
|
||||
|
||||
You might want to create a "test place" where you can test your package inside
|
||||
Roblox, or to get proper LSP support when developing your package.
|
||||
|
||||
To do this, you can create a `test-place.project.json` file which includes your
|
||||
package and the `roblox_packages` directory.
|
||||
|
||||
```json title="test-place.project.json"
|
||||
{
|
||||
"tree": {
|
||||
"$className": "DataModel",
|
||||
"ReplicatedStorage": {
|
||||
"package": {
|
||||
"$className": "Folder",
|
||||
"src": {
|
||||
"$path": "src"
|
||||
},
|
||||
"roblox_packages": {
|
||||
"$path": "roblox_packages"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can then run `rojo serve` with this project file:
|
||||
|
||||
```sh
|
||||
rojo serve test-place.project.json
|
||||
```
|
||||
|
||||
If you are using [Luau LSP](https://github.com/JohnnyMorganz/luau-lsp) you can
|
||||
change the `luau-lsp.sourcemap.rojoProjectFile` extension setting to
|
||||
`test-place.project.json` to get proper LSP support when developing your
|
||||
package.
|
||||
|
||||
### Differences from Wally
|
||||
|
||||
Those coming from [Wally](https://wally.run/) may be a bit confused by the
|
||||
way pesde handles Roblox packages.
|
||||
|
||||
In Wally, it is standard to have a `default.project.json` with the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"tree": {
|
||||
"$path": "src"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This will cause the `src` directory to be directly synced into Roblox.
|
||||
|
||||
In pesde, you should not have a `default.project.json` file in your package.
|
||||
Instead, you use the `build_files` field to specify what should be synced. This
|
||||
allows the consumer of your package to choose the sync tool they want to use,
|
||||
instead of being constrained to only using Rojo.
|
||||
|
||||
This has the effect that the structure of the files in the file system ends up
|
||||
being reflected inside Roblox.
|
||||
|
||||
With Wally, the structure that ends up in Roblox ends up looking like this:
|
||||
|
||||
<FileTree>
|
||||
|
||||
- Packages/
|
||||
- \_Index/
|
||||
- acme_package@1.0.0/
|
||||
- package/ (src/init.luau)
|
||||
- foo (src/foo.luau)
|
||||
- bar (src/bar.luau)
|
||||
- ...
|
||||
- dependency
|
||||
|
||||
</FileTree>
|
||||
|
||||
Whereas with pesde, it looks like this:
|
||||
|
||||
<FileTree>
|
||||
|
||||
- roblox_packages/
|
||||
- .pesde/
|
||||
- acme+package/
|
||||
- 1.0.0/
|
||||
- src/ (src/init.luau)
|
||||
- foo (src/foo.luau)
|
||||
- bar (src/bar.luau)
|
||||
- ...
|
||||
- roblox_packages/
|
||||
- dependency (roblox_packages/dependency.luau)
|
||||
|
||||
</FileTree>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue