Skip to content

Commit ded3b76

Browse files
SplizardSplizard
committed
update to graphics.gd
1 parent 1949efa commit ded3b76

File tree

8 files changed

+129
-296
lines changed

8 files changed

+129
-296
lines changed

‎src/content/docs/documentation/Overview/about.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@ title: About
33
description: About
44
---
55

6-
## What is Grow Graphics GD?
6+
## What is Graphics GD?
77
#### Community Supported Go Bindings for the Godot Game Engine
88

9-
I think it's a bit of an evolution from the branding/terminology of [seed](https://github.com/qlova/seed), a project I worked on in the past for building PWA 'apps' in Go. I'm not a big fan of Go modules having 'Go' in their name, ie. the thing they are based on with a 'go' prefix or suffix. I think it's important that projects develop their own independent identity.
9+
I think it's a bit of an evolution from the branding/terminology of [seed](https://github.com/qlova/seed), a project I worked on in the past for building PWA 'apps' in Go. I'm not a big fan of Go modules having 'Go' in their name, ie. the thing they are based on with a 'go' prefix or suffix. I think it's important that projects develop their own independent identity.
1010

1111

1212
I think the plant metaphors there are meant to convey 'a more organic holistic yet incremental development and design practice.
@@ -15,7 +15,7 @@ I think the plant metaphors there are meant to convey 'a more organic holistic y
1515
It's not enough for Go + Godot to just wrap Godot and call it a day, the project needs to be a synthesis in my opinion, with a holistic design that considers both Go & Godot together in order to be useful. You cannot expect Go developers to understand a whole bunch of technical things about Godot just so they can build a graphical application. In the same fashion, Godot developers primarily using GDScript, should be able to approach this project and it should be possible for them to write something for their Godot project in Go (without worrying too much about how to interact with Godot in a memory safe way).
1616

1717

18-
I understand `grow.graphics/gd` is not there yet, but the vision is certainly to be more approachable. Having a documentation website for this will go a long way!
18+
I understand `graphics.gd` is not there yet, but the vision is certainly to be more approachable. Having a documentation website for this will go a long way!
1919

2020

2121
So that's some context, I think there could be room for supporting/encouraging/developing more Go-oriented graphics modules within the grow.graphics umbrella, touching some lower level areas in a more approachable way, like OpenGL for example (which I am familiar with working in with Go), maybe even OpenXR and/or Vulkan. I wanted to target Godot in particular, as it is the most complete Open-Source solution out there, that has good cross-platform support and all the bells and whistles you need for almost any purpose.
@@ -27,5 +27,5 @@ I think Go is a very clean language, with excellent readability, not as complica
2727
I know there are other projects out there for 2D graphics like Ebiten, UI/UX projects like Gio, Fyne, there isn't a whole lot for 3D (although shoutout to G3N here for their efforts) so building on top of Godot makes a lot of sense, as it has a very large growing ecosystem and excellent support for 3D including animations and modern rendering features.
2828

2929

30-
Grow Graphics GD Maintainer,
31-
[Splizard](https://github.com/Splizard)
30+
Graphics GD Maintainer,
31+
[Splizard](https://github.com/Splizard)

‎src/content/docs/documentation/Overview/index.md

+88-95
Original file line numberDiff line numberDiff line change
@@ -3,160 +3,153 @@ title: Getting Started
33
description: Getting Started
44
---
55

6-
# Godot 4.2.2 + Go [![Go Reference](https://pkg.go.dev/badge/grow.graphics/gd.svg)](https://pkg.go.dev/grow.graphics/gd)
6+
# Graphics GD [![Go Reference](https://pkg.go.dev/badge/grow.graphics/gd.svg)](https://pkg.go.dev/grow.graphics/gd)
77

8-
This module provides a safe and simple way to work with Godot 4.2.2, in Go via the GDExtension interface.
8+
This module provides a safe performant way to work with graphics and game development in Go via the GDExtension
9+
interface of a supported graphics/game engine. So far, Godot 4.3 is the only officially supported engine.
910

1011
You can support the project and prioritise issues [here](https://buy.stripe.com/4gw14maETbnX3vOcMM)
1112

1213
```go
14+
// This file is all you need to start a project.
15+
// Save it somewhere, install the `gd` command and use `gd run` to get started.
1316
package main
1417

1518
import (
16-
"fmt"
19+
"graphics.gd/startup"
1720

18-
"grow.graphics/gd"
19-
"grow.graphics/gd/gdextension"
21+
"graphics.gd/classdb/Control"
22+
"graphics.gd/classdb/Label"
23+
"graphics.gd/classdb/SceneTree"
2024
)
2125

22-
type HelloWorld struct {
23-
gd.Class[HelloWorld, gd.SceneTree]
24-
}
25-
26-
// Ready implements the Godot MainLoop _initialize interface (virtual function).
27-
func (h *HelloWorld) Initialize(gd.Context) {
28-
fmt.Println("Hello World from Go!")
29-
}
30-
3126
func main() {
32-
godot, ok := gdextension.Link()
33-
if !ok {
34-
return
35-
}
36-
gd.RegisterClass[HelloWorld](godot)
27+
startup.Loader() // wait for the graphics/game engine to start up.
28+
hello := Label.New()
29+
hello.AsControl().SetAnchorsPreset(Control.PresetFullRect) // expand the label to take up the whole screen.
30+
hello.SetHorizontalAlignment(Label.HorizontalAlignmentCenter)
31+
hello.SetVerticalAlignment(Label.VerticalAlignmentCenter)
32+
hello.SetText("Hello, World!")
33+
SceneTree.Add(hello)
34+
startup.Engine()
3735
}
38-
3936
```
4037

4138
## Getting Started
42-
The module includes a drop-in replacement for the go command called `gd` that
43-
makes it easy to work with projects that run within Godot. It enables you to
44-
start developing a new project from a single main.go file, to install it, make
45-
sure that your `$GOPATH/bin` is in your `$PATH` and run:
39+
The module includes a drop-in replacement for the go command called `gd` that
40+
makes it easy to work with projects that run alongside a graphics/game engine.
41+
It enables you to start developing a new project from a single `main.go` file,
42+
to install it, make sure that your `$GOPATH/bin` is in your `$PATH` and run:
4643

4744
```sh
48-
go install grow.graphics/gd/cmd/gd@master
45+
go install graphics.gd/cmd/gd@master
4946
```
5047

51-
Now when you can run `gd run`, `gd test` on the main package in your project's
52-
directory, things will work as expected. The tool will create a "graphics"
53-
subdirectory where you can manage your assets via the Godot Editor.
48+
Now when you can run `gd run`, `gd test` on the main package in your project's
49+
directory, things will work as expected. The tool will create a "graphics"
50+
subdirectory where you can manage your assets via the Engine's Editor.
51+
52+
Running the command without any arguments will startup the Engine's Editor.
5453

55-
Running the command without any arguments will startup the editor.
54+
**NOTE** On linux (and macos if you have brew), `gd` will download an engine for you automatically!
55+
**HINT** On Windows, you'll want to
56+
[setup CGO](https://github.com/go101/go101/wiki/CGO-Environment-Setup).
5657

57-
**NOTE** On linux, `gd` will download Godot for you automatically!
58+
If you don't want to use the `gd` command, you can build a shared library with
59+
the `go` command directly:
60+
61+
```sh
62+
go build -o example.so -buildmode=c-shared
63+
```
5864

5965
## Design Principles
6066

61-
Godot classes are exported by the `gd` package and can be referred to by
62-
their standard Godot names, for example `gd.Object` is an
63-
[Object](https://docs.godotengine.org/en/latest/classes/class_object.html)
64-
reference. There's no inheritance, so to access the 'super' class, you need
65-
to call `Super()` on your custom 'Class'. All Godot classes have methods
66-
to cast to the classes they extend for example `AsObject()` or `AsNode2D()`.
67+
Each engine class is available as its own package under `classdb`. To import the
68+
`Node` class you can import `"graphics.gd/classdb/Node"` There's no inheritance,
69+
so to access a 'super' class, you need to call `Super()` on an Extension 'Class'.
70+
All engine classes have methods to cast to any sub-classes they extend for example
71+
`AsObject()` or `AsNode2D()`.
6772

6873
Methods have been renamed to follow Go conventions, so instead of
6974
underscores, methods are named as PascalCase. Keep this in mind when
70-
referring to the Godot documentation.
75+
referring to the Engine documentation.
7176

7277
https://docs.godotengine.org/en/latest/index.html
7378

74-
## Semi-Automatic Memory Management
75-
76-
Godot types are preferred over Go types, in order to keep allocations optional.
77-
All values are tied to a [gd.Context] type, which is either:
78-
79-
(a) a function argument and any values associated with it will be freed
80-
when the function returns.
81-
(b) builtin to the class you are extending, and any values associated
82-
with it will be freed when the class is destroyed by Godot.
79+
## Frame-Based Memory Management
8380

84-
This module aims to offer memory safety for race-free extensions, if you discover
85-
a way to unintentionally do something unsafe (like double free, use-after-free or
86-
a segfault), using methods on types exported by the root `gd` package please open
87-
an issue.
81+
Engine references must be 'used' every frame in order to remain alive, otherwise
82+
they will automatically be garbage collected each frame. You shouldn't have to
83+
worry about any memory management as long as you keep Engine references inside an
84+
extension class and don't hold onto references across frames. If you get an
85+
"expired pointer" error, it means either the reference has outlived its frame and
86+
has not been used since or the ownership of the value was transferred to the engine.
8887

8988
## Recommendations
9089

91-
Start with a main.go file, model your project in Go using structs to represent the
92-
world, space or state of your project. Go is an excellent language for textual
93-
representation. Use the `gd` command to launch the Godot editor when you want to
94-
create visual representation of your structures. The Godot editor is an excellent
95-
tool for importing media, managing assets and designing the visual and spatial aspects
96-
of a project. Don't forget to write tests!
90+
Start with a main.go file, model your project in Go using structs to represent the
91+
world, space or state of your project. Go is an excellent language for textual
92+
representation. Use the `gd` command to launch the Engine's editor when you want to
93+
create visual representation of your structures. The editor is excellent for importing
94+
media, managing assets and designing the visual and spatial aspects of a project.
95+
96+
**NOTE:** Don't forget to write tests!
9797

9898
## Where Do I Find?
9999

100100
```
101-
* Godot Class -> gd.{ClassName}
102-
* Godot Class Method -> gd.{ClassName}.{pascal(MethodName)}
103-
* Godot Utility Function -> gd.Context.{pascal(UtilityName)} OR gd.{pascal(UtilityName)} (pure)
104-
* Godot Enum -> gd.{EnumName}
105-
* Godot Enum Value -> gd.{EnumName}{EnumValueName}
106-
* Godot Singleton -> gd.{ClassName}(gd.Context) // function returns the singleton, they cannot be stored.
101+
* Engine Class -> graphics.gd/classdb/{ClassName}
102+
* Engine Class Method -> graphics.gd/classdb/{ClassName}.Instance.{pascal(MethodName)}
103+
* Utility Functions -> graphics.gd/variant/* and/or use the Go standard library.
104+
* Enum -> graphics.gd/classdb/{ClassName}.{EnumName}
105+
* Enum Value -> graphics.gd/classdb/{ClassName}.{EnumName}{EnumValueName}
106+
* Singletons -> graphics.gd/classdb/{ClassName}.{pascal(MethodName)} // package-level functions.
107107
```
108108

109109
## Performance
110-
It's feasible to write high performance code using this module, keep to Godot types where possible and avoid escaping memory to the heap in frequently called functions.
110+
It's feasible to write high performance code using this module, keep to Engine types where possible and avoid
111+
memory to the heap in frequently called functions. `Advanced` instances are available for each class which allow
112+
more fine-grained control over memory allocation.
111113

112-
## Zero Allocations
113-
Benchmarking shows method calls from Go -> Godot do not allocate in practice.
114+
### Zero Allocations
115+
Benchmarking shows method calls from Go -> Engine do not allocate in practice.
114116

115-
Allocations are currently unavoidable for GDScript -> Go calls (but not
116-
for class virtual method overrides such as `Ready` or `Process`, which
117+
Allocations are currently unavoidable for Script -> Go calls (but not
118+
for class virtual method overrides such as `Ready` or `Process`, which
117119
should be allocation free).
118120

119-
We've got some ideas to reduce allocations for GDScript -> Go calls, when
121+
We've got some ideas to reduce allocations for Script -> Go calls, when
120122
arguments fit entirely within registers. TBA.
121123

122124
## Examples
123-
124-
Run `make` in the example/src directory or manually build a C-shared library:
125-
126-
```sh
127-
cd example/src
128-
make # go build -o ./bin/example.so -buildmode=c-shared
129-
```
130-
131-
**NOTE:** the first time you build a project, it will take a little while to compile.
132-
After this, subsequent builds will be quite a bit faster!
133-
134-
Now open the example project in Godot from a terminal and you will be able to
135-
see Go printing things to the console.
136-
137-
There is also a [pong](https://github.com/grow-graphics/eg/blob/master/2d/pong/pong.go)
138-
example in the [examples](https://github.com/grow-graphics/eg) repo.
125+
There are a number of examples in the [examples](https://github.com/grow-graphics/eg)
126+
repo. All examples are designed to be run with `gd run` without any additional setup.
139127

140128
## Testing
141129
To run the go tests for this module `cd internal && gd test`.
142130

131+
## Supported Platforms
132+
133+
* Windows
134+
* Linux (including Steam Deck)
135+
* Mac (including Apple Silicon)
136+
* Android (including MetaQuest)
137+
* IOS (should work, untested)
138+
* Web (experimental) `GOOS=js GOARCH=wasm gd run`
139+
143140
## Known Limitations
144141

145-
* No support for indexed properties
146-
* No support for Godot class functions with varargs.
147-
* No support for script extensions.
148-
* 64bit support only.
149-
* Not tested on Windows.
150-
* No planned support for Web export or proprietary consoles.
151-
* Android/MetaQuest not working right now (support is planned).
142+
* No support for calling classdb methods that accept a variable number of arguments.
143+
* No support for Go 'scripts'.
144+
* 64bit only.
145+
* Web build needs work [read the discussion](https://github.com/grow-graphics/gd/discussions/69).
146+
* No planned support for proprietary consoles.
152147

153148
## See Also
154149

155-
* [Our pure Go zero-dependencies port of Godot's Color Class](https://github.com/grow-graphics/uc)
156-
* [Our pure Go zero-dependencies port of Godot's Math Variants](https://github.com/grow-graphics/xy)
157150
* [godot-go](https://github.com/godot-go/godot-go) (Another project aiming to support Go + Godot integration)
158151

159152
## Licensing
160-
This project is licensed under an MIT license (the same license as Godot), you can use
153+
This project is licensed under an MIT license (the same license as Godot), you can use
161154
it in any manner you can use the Godot engine. If you use this for a commercially successful
162-
project, please consider [financially supporting us](https://buy.stripe.com/4gw14maETbnX3vOcMM).
155+
project, please consider [financially supporting us](https://buy.stripe.com/4gw14maETbnX3vOcMM).

‎src/content/docs/documentation/Overview/license.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@ title: License
33
description: License
44
---
55

6-
76
## Licensing
8-
This project is licensed under an MIT license (the same license as Godot), you can use
7+
This project is licensed under an MIT license (the same license as Godot), you can use
98
it in any manner you can use the Godot engine. If you use this for a commercially successful
10-
project, please consider [financially supporting us](https://buy.stripe.com/4gw14maETbnX3vOcMM).
9+
project, please consider [financially supporting us](https://buy.stripe.com/4gw14maETbnX3vOcMM).

‎src/content/docs/documentation/Tutorials/helloworld.md

+11-12
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ description: Hello World Example
99
Installing the module
1010

1111
```sh
12-
go install grow.graphics/gd/cmd/gd@master
12+
go install graphics.gd/cmd/gd@master
1313
```
1414

1515
Create a new go project
@@ -25,12 +25,14 @@ package main
2525

2626
import (
2727
"fmt"
28-
"grow.graphics/gd"
29-
"grow.graphics/gd/gdextension"
28+
29+
"graphics.gd/classdb"
30+
"graphics.gd/classdb/Node2D"
31+
"graphics.gd/startup"
3032
)
3133

3234
type HelloWorld struct {
33-
gd.Class[HelloWorld, gd.Node2D]
35+
classdb.Extension[HelloWorld, Node2D.Instance]
3436
}
3537

3638
// Ready implements the Godot Node2D _ready interface (virtual function).
@@ -39,11 +41,8 @@ func (h *HelloWorld) Ready() {
3941
}
4042

4143
func main() {
42-
godot, ok := gdextension.Link()
43-
if !ok {
44-
return
45-
}
46-
gd.Register[HelloWorld](godot)
44+
classdb.Register[HelloWorld]()
45+
startup.Engine()
4746
}
4847
```
4948

@@ -55,7 +54,7 @@ go get -u
5554

5655
run the project
5756

58-
```sh
57+
```sh
5958
gd
6059
```
6160

@@ -67,10 +66,10 @@ Add it to the scene tree.
6766

6867
![Node tree](../../../../assets/tutorials/helloworld/helloworld2.png)
6968

70-
Save the project in Godot Editor.
69+
Save the project in Godot Editor.
7170

7271
In godot run the project or by running `gd run` in your terminal.
7372

7473
You may need to close and open the godot editor using `gd` if it cannot map the assets in the project.
7574

76-
If all is well check the editor and you should see the message `Hello World from Go!` in the console of your code editor.
75+
If all is well check the editor and you should see the message `Hello World from Go!` in the console of your code editor.

0 commit comments

Comments
 (0)