{"id":15722424,"url":"https://github.com/defold/extension-proto","last_synced_at":"2025-09-17T15:53:33.214Z","repository":{"id":146435091,"uuid":"536072968","full_name":"defold/extension-proto","owner":"defold","description":"This extension generates Lua bindings to encode and decode a predefined set of protobuf messages using Lua","archived":false,"fork":false,"pushed_at":"2024-05-27T22:52:31.000Z","size":16923,"stargazers_count":8,"open_issues_count":1,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-06T13:37:06.533Z","etag":null,"topics":["defold","protobuf"],"latest_commit_sha":null,"homepage":"","language":"C","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/defold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2022-09-13T10:28:33.000Z","updated_at":"2025-04-03T13:09:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"5a4cd1a2-f33d-432e-b5db-89086ff3a16e","html_url":"https://github.com/defold/extension-proto","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/defold/extension-proto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defold%2Fextension-proto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defold%2Fextension-proto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defold%2Fextension-proto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defold%2Fextension-proto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/defold","download_url":"https://codeload.github.com/defold/extension-proto/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defold%2Fextension-proto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275622147,"owners_count":25498323,"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","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["defold","protobuf"],"created_at":"2024-10-03T22:07:35.181Z","updated_at":"2025-09-17T15:53:33.191Z","avatar_url":"https://github.com/defold.png","language":"C","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"# extension-proto\nThis extension generates Lua bindings to encode and decode a predefined set of protobuf messages using Lua. The advantage with this solution is that there is no need to parse and compile protobuf message definitions, but the drawback is that the extension can only handle the protobuf messages that were processed when the extension was built. If you need an extension to also parse and compile protobuf message defintions then take a look at [defold-protobuf](https://defold.com/assets/protobuf/).\n\n\n## Requirements\nTo generate the Lua bindings you need python 3 and the `protobuf` and `pystache` packages. Install the packages using `pip`:\n\n```sh\n# install required python packages\npip install protobuf\npip install pystache\n```\n\n## Setup\nThis extension requires a bit more setup than most other Defold extensions before it can be used in a project:\n\n1. To use this extension in your Defold project, either [download a copy](https://github.com/defold/extension-proto/archive/refs/heads/master.zip) of the project, [create a fork](https://github.com/defold/extension-proto/fork) or [create a new repo from this template project](https://github.com/defold/extension-proto/generate).\n\n2. Add the protobuf message definitions (files with `.proto` extension) that the extension should handle to the `proto/` folder located in the root of the project. You can also load the `.proto` files from another location:\n   * Argument `-p` can be used when running `generate.py` to set list of paths where proto files are located (search paths)\n   * Argument `-f` can be used when running `generate.py` to define list of `.proto` files that will be used in the project\n\n3. Run `generate.py` to generate Lua bindings and other required files. The script does the following:\n   * Process all .proto files into a single intermediate data file in JSON format containing information about the protobuf messages\n   * Generate C representations of the protobuf messages for use at runtime\n   * Generate Defold extension source code with Lua bindings to encode and decode all protobuf messages\n   * Generate Defold script API definitions for the Lua bindings to enable auto-complete in the editor\n\nExample:\n\n```sh\n\n# Generate bindings for all '.proto' files in the 'proto' folder\ncd extension-proto\npython .generate.py\n\n# Generate bindings for file 'testproto3.proto' with imports located in './extension-proto/proto'\npython ./extension-proto/generate.py -f testproto3.proto -p ./extension-proto/proto\n```\n\nThe `generate.py` script uses the `protoc` compiler and the `protobuf-c` C-code generator:\n\n* `protoc` from https://github.com/protocolbuffers/protobuf/releases/tag/v21.6\n* `protobuf-c` from https://github.com/defold/protobuf-c\n\n\n## Run-time usage\nThe extension provides Lua bindings to encode and decode the protobuf messages defined in the `proto/` folder. The extension can encode and decode binary messages in protobuf 2 and protobuf 3 format. The extension can also encode and decode text messages in protobuf 2 format. Example:\n\n```\nsyntax = \"proto2\";\n\nmessage Person {\n  required int32 id = 1;\n  required string name = 2;\n  optional string email = 3;\n}\n```\n\nUsed in the extension like this:\n\n```\n-- Lua table matching\nlocal person = {\n\tid = 1,\n\tname = \"Bob\",\n\temail = \"bob@acme.com\",\n}\n\n-- encode Lua table to a binary protobuf message\nlocal msg = proto.encode_person(person)\n\n-- decode from a binary protobuf message to a Lua table\nlocal decoded = proto.decode_person(msg)\nassert(person.id == decoded.id)\nassert(person.name == decoded.name)\nassert(person.email == decoded.email)\n\n-- encode Lua table to a text message\nlocal msg_totext = proto.encode_person_totext(person)\n\n-- decode from a text message to a Lua table\nlocal decoded_fromtext = proto.decode_person_fromtext(msg_totext)\nassert(person.id == decoded_fromtext.id)\nassert(person.name == decoded_fromtext.name)\nassert(person.email == decoded_fromtext.email)\n```\n\n\n## Folder overview\n\n```\n|\n+-- extension-proto                        The Defold extension\n|   |\n|   +-- api\n|   |   |\n|   |   +-- extension-proto.script_api     (GENERATED) Lua API defintions for auto completion\n|   |   \n|   +-- include\n|   |   |\n|   |   +-- protobuf-c\n|   |       |\n|   |       +-- protobuf-c.h               The protobuf c runtime header\n|   |   \n|   +-- json\n|   |   |\n|   |   +-- proto.json                     (GENERATED) Protobuf message definitions converted\n|   |                                      to json. The json format is used when generating\n|   |                                      the other files used by the extension.\n|   +-- src                   \n|       |\n|       +-- protobuf-c\n|       |   |\n|       |   +-- protobuf-c.c               The protobuf c runtime source code\n|       |\n|       +-- protobuf-c-text\n|       |   |\n|       |   +-- ...                        The protobuf c text runtime source code\n|       |\n|       +-- proto.cpp                      (GENERATED) Extension source code\n|       +-- *-pb-c.c                       (GENERATED) Protobuf message source code\n|       +-- *-pb-c.h                       (GENERATED) Protobuf message header\n|\n+--- proto\n|    |\n|    +-- *.proto                           Protobuf message definitions\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefold%2Fextension-proto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefold%2Fextension-proto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefold%2Fextension-proto/lists"}