{"id":13830928,"url":"https://github.com/Tencent/ScriptX","last_synced_at":"2025-07-09T13:30:41.814Z","repository":{"id":40620152,"uuid":"349344200","full_name":"Tencent/ScriptX","owner":"Tencent","description":"A versatile script engine abstraction layer.","archived":false,"fork":false,"pushed_at":"2024-09-23T09:51:37.000Z","size":549,"stargazers_count":500,"open_issues_count":3,"forks_count":74,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-05-31T19:23:00.317Z","etag":null,"topics":["javascriptcore","lua","quickjs","script-engines","v8"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tencent.png","metadata":{"files":{"readme":"README-zh.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2021-03-19T07:58:49.000Z","updated_at":"2025-04-29T05:49:14.000Z","dependencies_parsed_at":"2023-12-03T14:32:00.929Z","dependency_job_id":"e3614186-7fc6-4362-8456-fe9e9f82fcfb","html_url":"https://github.com/Tencent/ScriptX","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Tencent/ScriptX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2FScriptX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2FScriptX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2FScriptX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2FScriptX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tencent","download_url":"https://codeload.github.com/Tencent/ScriptX/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2FScriptX/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264467895,"owners_count":23612997,"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":["javascriptcore","lua","quickjs","script-engines","v8"],"created_at":"2024-08-04T10:01:12.786Z","updated_at":"2025-07-09T13:30:41.211Z","avatar_url":"https://github.com/Tencent.png","language":"C++","readme":"\u003cimg width=\"350px\" align=\"left\" src=\"https://raw.githubusercontent.com/Tencent/ScriptX/main/docs/media/scriptx_logo.svg\"\u003e\u003c/img\u003e\n\n\u003ch2\u003eScriptX\u003c/h2\u003e\n\u003cp\u003e全能的脚本引擎抽象层\u003c/p\u003e\n\n---\n[![README-English](https://img.shields.io/badge/README-english-lightgreen)](README.md) [![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://www.apache.org/licenses/LICENSE-2.0) [![UnitTests](https://github.com/Tencent/ScriptX/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/Tencent/ScriptX/actions/workflows/unit_tests.yml)  ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/tencent/ScriptX) ![Lines of code](https://img.shields.io/tokei/lines/github/tencent/ScriptX) ![GitHub top language](https://img.shields.io/github/languages/top/tencent/ScriptX) [![Coverage Status](https://coveralls.io/repos/github/Tencent/ScriptX/badge.svg)](https://coveralls.io/github/Tencent/ScriptX)\n\n\n\n![ScriptX架构](docs/media/banner.webp)\n\nScriptX是一个脚本引擎抽象层。对下封装多种脚本引擎，对上暴露统一的API，使得上层调用者可以完全隔离底层的引擎实现(后端)。\n\nScriptX不仅隔离了几种JavaScript引擎，甚至可以隔离不同脚本语言，使得**上层仅需修改一个编译选项即可无缝切换脚本引擎和脚本语言**。\n\nScriptX的术语中，\"前端\"指对外的C++ API，\"后端\"则指不同的底层引擎，目前已经实现的后端有：V8, node.js, JavaScriptCore, WebAssembly, Lua.\n\n# 状态\n\n| 后端 | 语言 | 版本 | 状态 |\n| :----: |  :----:  | :----:  | :----: |\n| V8 | JavaScript | 7.4+\u003cbr\u003e([tested versions][tested_v8_versions]) | done |\n| JavaScriptCore | JavaScript | 7604.1.38.0.7+\u003cbr\u003e（iOS 10+/macOS10.12+) | done |\n| Node.js | JavaScript | 14.x+ | done |\n| QuickJs | JavaScript | 2024-01-13 | done |\n| WebAssembly | JavaScript | Emscripten-2.0.5+ | done |\n| Lua | Lua | 5.4+ | done |\n| CPython | Python |  | todo |\n| YARV | Ruby |  | todo |\n| Mono | C# |  | todo |\n\n[tested_v8_versions]: https://github.com/LanderlYoung/ScriptXTestLibs/blob/main/v8/supported_versions.txt\n\n# 简介\n\nScriptX 的接口使用现代C++特性。并且做到100%符合C++标准，完全跨平台。\n\n所有API以`ScriptX.h`聚合头文件暴露出来。\n\n设计目标： **多语言** | **多引擎实现** | **高性能** | **API易用** | **跨平台**\n\n# 第一印象\n\n我们通过一段比较完整的代码来对ScriptX留下一个整体印象。\n\n```c++\nEngineScope enter(engine);\ntry {\n  engine-\u003eeval(\"function fibo(x) { if (x\u003c=2 ) return 1; else return fibo(x-1) + fibo(x-2) }\");\n  Local\u003cFunction\u003e fibo = engine-\u003eget(\"fibo\").asFunction();\n  Local\u003cValue\u003e ret = fibo.call({}, 10);\n  ret.asNumber().toInt32() == 55;\n\n  auto log = Function::newFunction(\n      [](const std::string\u0026 msg) {\n        std::cerr \u003c\u003c \"[log]: \" \u003c\u003c msg \u003c\u003c std::endl;\n      });\n  // or use: Function::newFunction(std::puts);\n  engine-\u003eset(\"log\", log);\n  engine-\u003eeval(\"log('hello world');\");\n\n  auto json = engine-\u003eeval(R\"( JSON.parse('{\"length\":1,\"info\":{\"version\": \"1.18\",\"time\":132}}'); )\")\n                  .asObject();\n  json.get(\"length\").asNumber().toInt32() == 1;\n\n  auto info = json.get(\"info\").asObject();\n  info.get(\"version\").asString().toString() ==  \"1.18\";\n  info.get(\"time\").asNumber().toInt32() == 132;\n\n  Local\u003cObject\u003e bind = engine-\u003eeval(\"...\").asObject();\n  MyBind* ptr = engine-\u003egetNativeInstance\u003cMyBind\u003e(bind);\n  ptr-\u003ecallCppFunction();\n\n} catch (Exception\u0026 e) {\n  FAIL() \u003c\u003c e.message() \u003c\u003c e.stacktrace();\n  // or FAIL() \u003c\u003c e;\n}\n```\n\n1. 使用 `EngineScope` 进入引擎环境\n2. 绝大多是API可以接受C++原生类型作为参数，内部自动转换类型\n3. 可以从C/C++函数直接创建脚本函数（native 绑定）\n4. 支持脚本的异常处理\n5. API强类型\n\n# 特性介绍\n\n## 1. 支持多种引擎，多脚本语言\nScriptX设计之初就目标为支持多种脚本语言，并在JavaScript上实现了V8和JavaScriptCore的引擎封装。\n后续为了验证ScriptX的多语言设计，实现了完整的Lua绑定。\n目前针对WebAssembly的支持也已经完成。\n\n## 2. 现代的 C++ API\n\nAPI设计上符合现代 C++ 风格，如：\n1. 三种引用类型 Local/Global/Weak，使用copy, move语义实现自动的内存管理（自动引用计数）\n2. 使用 variadic template 支持非常方便的 Function::call 语法\n3. 使用 Template Meta-Programing 实现直接绑定C++函数\n\n现代语言特性，引用空指针安全（nullibility safety 请参考kotlin的概念）。\n\n\u003e 注：ScriptX要求C++17（或1z）以上的编译器支持，并需要打开异常特性，（可以关闭RTTI特性）。\n\n## 3. 高性能\n高性能是ScriptX设计上的重要指标。在实现过程中也充分体现了 Zero-Overhead 的C++思想。并在增加功能特性的时候通过相关的性能测试。\n\n![性能测试对比数据](docs/media/performance.webp)\n测试指标：单次JS到C++函数调用耗时，微秒\n\n测试环境：iMac i9-9900k 32G RAM @macOS 10.15\n\n性能测试表示，在Release模式下，ScriptX可以达到几乎和原生绑定相同的性能。（由于ScriptX使用大量模板，请勿在Debug版进行性能测试）\n\n## 4. 方便的异常处理\n\nScriptX通过一系列的技术手段实现了脚本的异常和C++异常相互打通的能力。在调用引擎API时无需判断返回值，可以使用异常统一处理，避免crash。\n\n比如使用者可以在C++层catch住js代码抛的异常，并获取message和堆栈；也可以在native函数里抛一个C++异常(`script::Exception`) 并透传到js代码中去。\n\n详见 [ExceptionTest](test/src/ExceptionTest.cc) 及 [相关文档](docs/zh/Exception.md)\n\n## 5. 易用的API\n\n\u003e 易用的API =\u003e 开心的工程师 =\u003e 高效 =\u003e 高质量\n\nScriptX 设计的时候充分考虑到API的易用性，包括操作友好简单，不易出错，错误信息明显，便于定位问题等。在这样的指导思想之下ScriptX做了很多原生引擎做不了的事情。\n\n比如：V8在destroy的时候是不执行GC的，导致很多绑定的native类不能释放。ScriptX做了额外的逻辑处理这个情况。\n\nV8和JSCore要求在finalize回调中不能调用ScriptX的其他API，否则会crash，这也导致代码逻辑很难实现。ScriptX借助MessageQueue完美规避这个问题。\n\nV8和JSCore的全局引用都必须在engine destroy之前全部释放掉，否则就会引起crash、不能destroy等问题。ScriptX则保证在Engine destroy的时候主动reset所有 Global / Weak 引用。\n\n## 6. 简单高效的绑定API\n\n当app作为宿主使用脚本引擎时，通常都是需要注入大量native 绑定的 函数/类 来为脚本逻辑提供能力。ScriptX 设计的`ClassDeifine`相关绑定API简单易用，并且可以支持直接绑定C++函数，极大的提升工作效率。\n\n## 7. 可以与原生引擎API互操作\nScriptX再提供引擎封装的同时，也提供了一套工具方法实现原生类型和ScriptX类型的相互转换。\n\n详见 [InteroperateTest](test/src/InteroperateTest.cc) 及 [相关文档](docs/zh/Interop.md)\n\n# 代码质量\n\n代码质量高标准要求\n1. 上百个测试用例，**单测覆盖率达 90+%**\n2.  **圈复杂度仅有 1.18**。\n3. 借助clang-format保证代码格式统一。\n4. 使用clang-tidy发现潜在问题。\n5. 在clang和MSVC编译器上都打开了\"warning as error\"级别的错误信息。\n\n# 代码目录结构\n\n```text\nroot\n├── README.md\n├── src\n│   ├── Engine.h\n│   └── ...\n├── backend\n│   ├── JavaScriptCore\n│   ├── Lua\n│   ├── Python\n│   ├── QuickJs\n│   ├── Ruby\n│   ├── SpiderMonkey\n│   ├── Template\n│   ├── V8\n│   ├── WKWebView\n│   └── WebAssembly\n├── docs\n│   ├── Basics.md\n│   └── ...\n└── test\n    ├── CMakeLists.txt\n    └── src\n        ├── Demo.cc\n        └── ...\n```\n\n1. `src`: 对外API，主要是头文件\n2. `backend`: 各种引擎后端的实现\n3. `docs`: 丰富的文档\n4. `test`: 各种单元测试\n\n# 上手文档\n\nScriptX 中的一些重要类：\n1. `ScriptEngine`\n2. `EngineScope`\n2. `Exception`\n3. `Value`, `Null`, `Object`, `String`, `Number`, `Boolean`, `Function`, `Array`, `ByteBuffer`, `Unsupported`\n4. `Local\u003cValue\u003e`, `Local\u003cNull\u003e`, `Local\u003cObject\u003e`, `Local\u003cString\u003e`, `Local\u003cNumber\u003e`, `Local\u003cBoolean\u003e`, `Local\u003cFunction\u003e`, `Local\u003cArray\u003e`, `Local\u003cByteBuffer\u003e`, `Local\u003cUnsupported\u003e`\n5. `Global\u003cT\u003e`, `Weak\u003cT\u003e`\n\n在正式使用ScriptX之前，请花半个小时**仔细阅读**[项目文档](docs/zh/TOC.md)，并熟悉 ScriptX 中的若干概念。\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTencent%2FScriptX","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTencent%2FScriptX","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTencent%2FScriptX/lists"}