{"id":15176777,"url":"https://github.com/grow-graphics/gd","last_synced_at":"2025-05-16T09:06:39.930Z","repository":{"id":59044151,"uuid":"527166483","full_name":"grow-graphics/gd","owner":"grow-graphics","description":"Go + Godot 4.4","archived":false,"fork":false,"pushed_at":"2025-05-08T10:24:12.000Z","size":38241,"stargazers_count":346,"open_issues_count":4,"forks_count":19,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-08T11:34:14.635Z","etag":null,"topics":["bindings","gdextension","godot","golang","wrapper"],"latest_commit_sha":null,"homepage":"https://learn.graphics.gd","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grow-graphics.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"License","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":["https://buy.stripe.com/4gw14maETbnX3vOcMM"]}},"created_at":"2022-08-21T09:57:42.000Z","updated_at":"2025-05-08T10:24:16.000Z","dependencies_parsed_at":"2024-03-05T06:43:37.818Z","dependency_job_id":"28cea291-f258-486d-b4c9-b803aa3d9d39","html_url":"https://github.com/grow-graphics/gd","commit_stats":{"total_commits":263,"total_committers":4,"mean_commits":65.75,"dds":0.08365019011406849,"last_synced_commit":"30574d0ebf3ee89cc464c55f3ada8710fd24f616"},"previous_names":["grow-graphics/gd","readykit/gd"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grow-graphics%2Fgd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grow-graphics%2Fgd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grow-graphics%2Fgd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grow-graphics%2Fgd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grow-graphics","download_url":"https://codeload.github.com/grow-graphics/gd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501558,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bindings","gdextension","godot","golang","wrapper"],"created_at":"2024-09-27T13:42:22.646Z","updated_at":"2025-05-16T09:06:34.868Z","avatar_url":"https://github.com/grow-graphics.png","language":"Go","funding_links":["https://buy.stripe.com/4gw14maETbnX3vOcMM"],"categories":[],"sub_categories":[],"readme":"# Graphics GD [![Go Reference](https://pkg.go.dev/badge/graphics.gd.svg)](https://pkg.go.dev/graphics.gd)\n\nA safe performant way to work with graphics and game development in Go via\nthe GDExtension interface of any supported graphics/game engine (ie. Godot 4.4).\n\n_Why use graphics.gd?_\n\n* [Write shaders in Go!](./shaders/Readme.md)\n* Unlike with other options, RIDs, callables and dictionary arguments are all distinctly typed.\n* A good balance of performance and convenience.\n* General-purpose pure-Go 'variant' packages, reuse them in any Go project.\n* Recompile your code quickly, with a build experience similar to a scripting language.\n\nNot just a wrapper! graphics.gd has been holistically designed and curated from the ground up to provide a cohesive way to interface with the engine.\n\nWe would love you to take part in our [active discussions](https://github.com/grow-graphics/gd/discussions)\nsection with any questions, comments or feedback you may have. Show us what you're building!\n\n```go\n// This file is all you need to start a project.\n// Save it somewhere, install the `gd` command and use `gd run` to get started.\npackage main\n\nimport (\n\t\"graphics.gd/startup\"\n\n\t\"graphics.gd/classdb/Control\"\n\t\"graphics.gd/classdb/Label\"\n\t\"graphics.gd/classdb/SceneTree\"\n)\n\nfunc main() {\n\tstartup.LoadingScene() // setup the SceneTree and wait until we have access to engine functionality\n\thello := Label.New()\n\thello.AsControl().SetAnchorsPreset(Control.PresetFullRect) // expand the label to take up the whole screen.\n\thello.SetHorizontalAlignment(Label.HorizontalAlignmentCenter)\n\thello.SetVerticalAlignment(Label.VerticalAlignmentCenter)\n\thello.SetText(\"Hello, World!\")\n\tSceneTree.Add(hello)\n\tstartup.Scene() // starts up the scene and blocks until the engine shuts down.\n}\n```\n\nYou can help fund the project, motivate development and prioritise issues [here](https://buy.stripe.com/4gw14maETbnX3vOcMM)\n\n## Getting Started\nThe module includes a drop-in replacement for the go command called `gd` that\nmakes it easy to work with projects that run alongside a graphics/game engine.\nIt enables you to start developing a new project from a single `main.go` file,\nto install it, make sure that your `$GOPATH/bin` is in your `$PATH` and run:\n\n```sh\n\tgo install graphics.gd/cmd/gd@master\n```\n\nNow when you can run `gd run`, `gd test` on the main package in your project's\ndirectory, things will work as expected. The tool will create a \"graphics\"\nsubdirectory where you can manage your assets via the Engine's Editor.\n\nRunning the command without any arguments will startup the Engine's Editor.\n\n**NOTE** On linux (and macos if you have brew), `gd` will download an engine for you automatically!\n**HINT**  On Windows, you'll want to\n[setup CGO](https://github.com/go101/go101/wiki/CGO-Environment-Setup).\n\nIf you don't want to use the `gd` command, you can build a shared library with\nthe `go` command directly:\n\n```sh\ngo build -o example.so -buildmode=c-shared\n```\n\n## Design Principles\n\nEach engine class is available as its own package under `classdb`. To import the\n`Node` class you can import `\"graphics.gd/classdb/Node\"` There's no inheritance,\nso to access a 'super' class, you need to call `Super()` on an Extension 'Class'.\nAll engine classes have methods to cast to any sub-classes they extend for example\n`AsObject()` or `AsNode2D()`.\n\nMethods have been renamed to follow Go conventions, so instead of\nunderscores, methods are named as PascalCase. Keep this in mind when\nreferring to the Engine documentation.\n\nhttps://docs.godotengine.org/en/latest/index.html\n\n## Frame-Based Memory Management\n\nEngine references must be 'used' every frame in order to remain alive, otherwise\nthey will automatically be garbage collected each frame. You shouldn't have to\nworry about any memory management as long as you keep Engine references inside an\nextension class and don't hold onto references across frames. If you get an\n\"expired pointer\" error, it means either the reference has outlived its frame and\nhas not been used since or the ownership of the value was transferred to the engine.\n\nThe project aims to provide as much memory safety as possible for working with the\nEngine, please open an issue if you determine there to be any issues here.\n\n## Recommendations\n\nStart with a main.go file, model your project in Go using structs to represent the\nworld, space or state of your project. Go is an excellent language for textual\nrepresentation. Use the `gd` command to launch the Engine's editor when you want to\ncreate visual representation of your structures. The editor is excellent for importing\nmedia, managing assets and designing the visual and spatial aspects  of a project.\n\n**NOTE:** Don't forget to write tests!\n\n## Where Do I Find?\nCtrl+F in the project for a specific `//gd:symbol` to find the matching Go symbol.\n```\n* Engine Class           -\u003e `//gd:ClassName`\n* Engine Class Method    -\u003e `//gd:ClassName.method_name`\n* Utility Functions      -\u003e `//gd:utility_function_name`\n* Enum                   -\u003e `//gd:ClassName.EnumName`\n```\n\n## Variant Type Table\n\n| Engine Type        | Convenience Type          | Best Performance Type           |\n| ------------------ | ------------------------- | ------------------------------- |\n| Variant            | `any`                     | `variant.Any`                   |\n| bool               | `bool`                    | `bool`                          |\n| int                | `int`                     | `int64`                         |\n| float              | `Float.X`                 | `Float.X`                       |\n| String             | `string`                  | `String.Readable`               |\n| Vector2            | `Vector2.XY`              | `Vector2.XY`                    |\n| Vector2i           | `Vector2i.XY`             | `Vector2i.XY`                   |\n| Rect2              | `Rect2.PositionSize`      | `Rect2.PositionSize`            |\n| Rect2i             | `Rect2i.PositionSize`     | `Rect2i.PositionSize`           |\n| Vector3            | `Vector3.XYZ`             | `Vector3.XYZ`                   |\n| Vector3i           | `Vector3i.XYZ`            | `Vector3i.XYZ`                  |\n| Transform2D        | `Transform2D`             | `Transform2D`                   |\n| Vector4            | `Vector4.XYZW`            | `Vector4.XYZW`                  |\n| Vector4i           | `Vector4i.XYZW`           | `Vector4i.XYZW`                 |\n| Plane              | `Plane.NormalD`           | `Plane.NormalD`                 |\n| Quaternion         | `Quaternion.IJKL`         | `Quaternion.IJKL`               |\n| AABB               | `AABB.PositionSize`       | `AABB.PositionSize`             |\n| Basis              | `Basis.XYZ`               | `Basis.XYZ`                     |\n| Transform3D        | `Transform3D.BasisOrigin` | `Transform3D.BasisOrigin`       |\n| Projection         | `Projection.XYZW`         | `Projection.XYZW`               |\n| Color              | `Color.RGBA`              | `Color.RGBA`                    |\n| StringName         | `string`                  | `String.Name`                   |\n| NodePath           | `string`                  | `Path.ToNode`                   |\n| Signal             | `chan T`                  | `Signal.Any`                    |\n| RID                | `RID.T`                   | `RID.Any`                       |\n| Object             | `T.Instance`              | `T.Advanced`                    |\n| Callable           | `func(...T) (...T)`       | `Callable.Function`             |\n| Dictionary         | `struct/map[T]T`          | `Dictionary.Any`                |\n| Array              | `[]T`                     | `Array.Any`                     |\n| PackedByteArray    | `[]byte`                  | `Packed.Bytes`                  |\n| PackedInt32Array   | `[]int32`                 | `Packed.Array[int32]`           |\n| PackedInt64Array   | `[]int64`                 | `Packed.Array[int64]`           |\n| PackedFloat32Array | `[]float32`               | `Packed.Array[float32]`         |\n| PackedFloat64Array | `[]float64`               | `Packed.Array[float64]`         |\n| PackedStringArray  | `[]string`                | `Packed.Array[String.Readable]` |\n| PackedVector2Array | `[]Vector2.XY`            | `Packed.Array[Vector2.XY]`      |\n| PackedVector3Array | `[]Vector3.XYZ`           | `Packed.Array[Vector3.XYZ]`     |\n| PackedColorArray   | `[]Color.RGBA`            | `Packed.Array[Color.RGBA]`      |\n| PackedVector4Array | `[]Vector4.XYZW`          | `Packed.Array[Vector4.XYZW]`    |\n\n## Performance\nIt's feasible to write high performance code using this module, keep to Engine types where possible and avoid\nallocating memory on the heap in frequently called functions. `Advanced` instances are available for each class\nwhich allow more fine-grained control over memory allocations.\n\nBenchmarking shows `Advanced` method calls from Go -\u003e Engine do not allocate in practice.\n\nAllocations are currently unavoidable for any Script -\u003e Go calls (but not\nfor `Advanced` class virtual method overrides such as `Ready` or `Process`,\nwhich do not allocate in practice).\n\nWe've got some ideas to reduce allocations for Script -\u003e Go calls, when\narguments fit entirely within registers. TBA.\n\n## Examples\nThere are a number of examples in the [examples](https://github.com/grow-graphics/eg)\nrepo. All examples are designed to be run with `gd run` without any additional setup.\n\n## Supported Platforms\n\n* Windows\n* Linux   (including Steam Deck)\n* Mac     (including Apple Silicon)\n* Android (including MetaQuest)\n* IOS     (should work, untested)\n* Web     (experimental) `GOOS=js GOARCH=wasm gd run`\n\n## Known Limitations\n\n* No support for calling classdb methods that accept a variable number of arguments.\n* No support for Go 'scripts'.\n* 64bit only (arm64 \u0026\u0026 amd64).\n* No console support, will likely be achieved in the future with WASM.\n\n## Contributing\n\nThe best way you can contribute to graphics.gd is to **try it**, this project needs you to find out\nwhat's working and what doesn't, so do please let us know of any trouble that you run into! Any\nexamples you can contribute are more than welcome.\n\nThe next best thing you can do to help is improve the Variant packages, these are general-purpose\npackages inspired by the Godot engine's Variant types. Specifically any changes you can make to\noptimize functionality and/or improve test coverage of these packages is more than welcome\n(such as specialized assembly routines for vector operations, anyone?).\n\nIf you enjoy hunting down memory-safety issues, we would appreciate any issues being opened on\nthis front.\n\nThirdly, the project needs more tests to ensure that everything is working, the best way you can\nguarantee that graphics.gd won't break on you is to contribute tests that cover the functionality\nyou need!\n\nTo run the go tests for graphics.gd, cd into the repo and run `cd internal \u0026\u0026 gd test`.\n\nLastly, spread the word and let people know about graphics.gd!\n\n## See Also\n\n* [godot-go](https://github.com/godot-go/godot-go) (Another project aiming to support Go + Godot integration)\n\n## Licensing\nThis project is licensed under an MIT license (the same license as Godot), you can use it in any manner\nyou can use the Godot engine. If you use this project for any commercially successful products, please\nconsider [financially supporting us](https://buy.stripe.com/4gw14maETbnX3vOcMM) to show your appreciation!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrow-graphics%2Fgd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrow-graphics%2Fgd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrow-graphics%2Fgd/lists"}