{"id":27549040,"url":"https://github.com/bridge-core/molang","last_synced_at":"2025-04-19T04:34:27.353Z","repository":{"id":36944321,"uuid":"230114098","full_name":"bridge-core/molang","owner":"bridge-core","description":"Fast MoLang parser for JavaScript/TypeScript applications","archived":false,"fork":false,"pushed_at":"2024-08-02T00:19:25.000Z","size":1041,"stargazers_count":18,"open_issues_count":4,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T21:03:49.382Z","etag":null,"topics":["hacktoberfest","interpreter","javascript","molang","molang-parser","parser","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/bridge-core.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":"2019-12-25T14:30:01.000Z","updated_at":"2025-02-02T06:29:07.000Z","dependencies_parsed_at":"2024-12-27T23:13:45.656Z","dependency_job_id":"ab38321e-b1eb-4aa7-a863-b9363df94d1f","html_url":"https://github.com/bridge-core/molang","commit_stats":{"total_commits":229,"total_committers":6,"mean_commits":"38.166666666666664","dds":0.0873362445414847,"last_synced_commit":"bd7f7486e03ff2ec3846e1d7493a17d71004ba90"},"previous_names":["solveddev/molang"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bridge-core%2Fmolang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bridge-core%2Fmolang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bridge-core%2Fmolang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bridge-core%2Fmolang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bridge-core","download_url":"https://codeload.github.com/bridge-core/molang/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248951418,"owners_count":21188413,"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":["hacktoberfest","interpreter","javascript","molang","molang-parser","parser","typescript"],"created_at":"2025-04-19T04:33:04.959Z","updated_at":"2025-04-19T04:34:27.336Z","avatar_url":"https://github.com/bridge-core.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Molang\n\nA fast Molang parser used and developed by the bridge. team. This library has full support for all of Minecraft's Molang features.\n\n## About\n\n\u003e Molang is a simple expression-based language designed for fast calculation of values at run-time. Its focus is solely to enable script-like capabilities in high-performance systems where JavaScript is not performant at scale. We need scripting capabilities in these low-level systems to support end-user modding capabilities, custom entities, rendering, and animations.\n\n\\- From the Minecraft documentation\n\n## Installation\n\n-   `npm i molang`\n\n    **or**\n\n-   Download the `dist/main.web.js` file and add the script to your HTML page (library access via global `Molang` object).\n\n## Basic Usage\n\nTo execute a basic Molang statement, first construct a new instance of the `Molang` class. The first constructor argument is the environment your Molang script will have access to and the second argument configures the Molang interpreter. Take a look at the `IParserConfig` interface [for a list of all available options](https://github.com/bridge-core/Molang/blob/master/lib/main.ts).\n\n`molang.execute(...)` simply executes a Molang script and returns the value it evaluates to.\n\n```javascript\nimport { Molang } from 'molang'\n\nconst molang = new Molang(\n\t{\n\t\tquery: {\n\t\t\tx: 0,\n\t\t\tget(val) {\n\t\t\t\treturn val + 4\n\t\t\t},\n\t\t},\n\t},\n\t{ useCache: true }\n)\nmolang.execute('query.x + query.get(3) == 7')\n```\n\n### Setting up nested environments\n\nFor the context switching operator \"-\u003e\", you can set up nested environments like this:\n\n```javascript\nimport { Molang, Context } from 'molang'\n\nconst molang = new Molang({\n\tquery: {\n\t\ttest: 1,\n\t},\n\tcontext: {\n\t\tother: new Context({\n\t\t\tquery: { test: 2 },\n\t\t}),\n\t},\n})\n\nmolang.execute('query.test') // Returns 1\nmolang.execute('context.other-\u003equery.test') // Returns 2\n```\n\n## Using Custom Molang Functions\n\nCustom Molang functions were designed to support `.molang` files within bridge.\n\n```javascript\nimport { CustomMolang } from 'molang'\n\nconst customMolang = new CustomMolang({})\n\nconst molangFunctions = ... // Somehow load Molang input that defines custom functions\n\n// Make custom functions known to Molang parser\ncustomMolang.parse(molangFunctions)\n\nconst molangSource = ... // Somehow load Molang source from JSON files\n\nconst transformedSource = customMolang.transform(molangSource)\n... // Write the transformed source string back to the JSON file or do further processing\n```\n\nA custom Molang function is defined like this:\n\n```javascript\nfunction('sq', 'base', {\n\treturn math.pow(a.base, 2);\n});\n\nfunction('pow', 'base', 'exp', {\n\treturn a.exp == 0 ? 1 : a.base * f.pow(a.base, a.exp - 1);\n});\n```\n\n-   The first argument always defines the function name\n-   All following arguments except the last one define input arguments\n-   The last argument is the function body\n-   Temporary variables get scoped to the current function body automatically\n-   Basic recursion is supported as long as the interpreter can stop the recursive calls at compile-time\n-   To call a function inside of Molang scripts, simply do `f.sq(2)` or `f.pow(3, 2)`\n\n## Using AST Scripts\n\nYou can write abitrary scripts to traverse the abstract syntax tree this library builds.\n\n```javascript\nimport { Molang, expressions } from 'molang'\n\nconst molang = new Molang()\n\nlet ast = molang.parse(`context.other-\u003equery.something + 1`)\nconst { NumberExpression } = expressions\n\n// This increments all numbers within a Molang script\nast = ast.walk((expr) =\u003e {\n\tif (expr instanceof NumberExpression)\n\t\treturn new NumberExpression(expr.eval() + 1)\n})\n\nconst output = ast.toString() // 'context.other-\u003equery.something+2'\n```\n\n## Performance\n\n**Disclaimer:** Both bridge.'s Molang library and Blockbench's library are usually fast enough. However, bridge.'s Molang interpreter shines when it comes to executing a wide variety of different scripts (ineffective cache) where it is up to 10x faster at interpreting a vanilla Molang script.\n\n### Vanilla Script\n\nThe following script gets executed 100,000 times for the first test:\n\n`variable.hand_bob = query.life_time \u003c 0.01 ? 0.0 : variable.hand_bob + ((query.is_on_ground \u0026\u0026 query.is_alive ? math.clamp(math.sqrt(math.pow(query.position_delta(0), 2.0) + math.pow(query.position_delta(2), 2.0)), 0.0, 0.1) : 0.0) - variable.hand_bob) * 0.02;`\n\n### Molang\n\nUsed by bridge.\n\n| Test                       | Average Time |\n| -------------------------- | ------------ |\n| Parse \u0026 Execute (uncached) | 1253.332ms   |\n| Parse \u0026 Execute (cached)   | 90.036ms     |\n\n### MolangJS\n\nUsed by Blockbench \u0026 Snowstorm\n| Test | Average Time |\n| -------------------------- | ------------ |\n| Parse \u0026 Execute (uncached) | 11872ms |\n| Parse \u0026 Execute (cached) | 185.299ms |\n\n### Early Return\n\nThe same script as above, except that we now insert a \"return 1;\" in front of it. bridge.'s interpreter is smart enough to figure out that the whole expression is static after it parsed `return 1;`. These kinds of optimizations can be found throughout our library.\n\n### Molang\n\nUsed by bridge.\n\n| Test                       | Average Time |\n| -------------------------- | ------------ |\n| Parse \u0026 Execute (uncached) | 103.61ms     |\n| Parse \u0026 Execute (cached)   | 8.835ms      |\n\n### MolangJS\n\nUsed by Blockbench \u0026 Snowstorm\n| Test | Average Time |\n| -------------------------- | ------------ |\n| Parse \u0026 Execute (uncached) | 13230.682ms |\n| Parse \u0026 Execute (cached) | 147.786ms |\n\n## Molang Playground\n\nWe have built a very basic Molang playground with this interpreter. You can use it at [bridge-core.github.io/molang-playground](https://bridge-core.github.io/molang-playground).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbridge-core%2Fmolang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbridge-core%2Fmolang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbridge-core%2Fmolang/lists"}