在C和Objective-C中绑定JavaScript--------------------------cocos2d-x 3.0正式版本（7.15）



引言

C/Objective-C语言中的JavaScript Bindings 是介于本地代码(C or Objective-C)和 JavaScript(JS)代码之间的“胶水”代码(封装代码)。JSB能实现JS和本地代码之间的 互相调用 。

这意味着你可以使用JS在你喜欢的本地库之间互相调用。例如,你可以在JS中创建一个 cocos2d的粒子系统,而它的逻辑和渲染是本地代码执行。或者你可以在JS中创建一个 Chipmunk的物理世界,而所有物理仿真,包括碰撞检测都是本地代码执行。

JSB Layer

JS代码由Mozilla的JS虚拟机(VM)SpiderMonkey解析。使用SpiderMonekey最新的稳 定版本(本文使用的是v14.0.1)。JS VM通过JSB扩展支持自定义类型,自定义结构体和 Objective-C对象。

JSB有一套灵活的重命名规则用来设定哪些类、方法、函数和结构体将被解析或忽略,并确 定哪些方法是回调。为了方便的创建这些规则,它支持正则表达式。

这项技术正被Zynga公司用在游戏的快速开发和原型设计中。现在,让我们在cocos2d-iphone,Chipmunk和CoCosBuilder Reader上使用它。

主要特点

JSB的亮点:

• 支持Objective-C/C的任何库
• 自动生成JS Bindings(“胶水”代码)
• 不需要修改库的源代码,或自动生成的代码
• 有一套强大的规则可定制JS API 的生成
• 自动在JS对象/类型 和 Objective-C对象/结构体/类型 之间相互转换
• 在JS中支持本地对象的子类
• 支持回调

创建自己的Bindings

简明步骤
1.下载JSB(git下载地址)

$git clone git://github.com/zynga/jsbindings.git

2.生成BridgeSupport 文件,假设项目名是CocosDenshion

$cd ~/src/CocosDenshion/CocosDenshion$gen_bridge_metadata -F complete --no-64-bit -c '-DNDEBUG -I.' *.h -o ~/some/path/CocosDenshion.bridgesupport

3.生成补充文件

$cd ~/src/CocosDenshion/CocosDenshion$~/jsb/generate_complement.py -o ~/some/path/CocosDenshion-complement.txt *.h

4.创建JSB配置文件

$vim ~/some/path/CocosDenshion_jsb.ini

5.运行JSB生成脚本

$~/jsb/generate_js_bindings.py -c ~/som/path/CocosDenshion_jsb.ini

6.导入刚才自动生成的文件和JSB源码文件到你的xcode项目中

7.导入SpiderMonkey和JRSwizzle到你的xcode项目
所有文件能在这里找到:

https://github.com/zynga/jsbindings/tree/master/configs/CocosDenshion

详细步骤

JSB中有一个名为generate_js_bindings.py的脚本, 这个脚本会生成“胶水”代码。脚本需 要一个配置文件,其中包含解析规则和BridgeSupport文件。

BridgeSupport文件由OS X下的gen_bridge_metada脚本生成,生成的是一些xml文件包 含了类名,方法名,参数,返回值,内部结构体,常量等信息.

gen_bridge_metada,内部使用clang 解析本地代码。输出的内容是非常可靠的,但不幸的 是,它不完整:丢失了类继承关系、协议和属性信息。这就是为什么JSB包含另一个python脚本generate_js_complement.py, 它生成丢失的信息。

当配置文件准备好,就可以运行generate_js_bindings.py 脚本生成“胶水”代码。

总结,JSB配置文件的结构是

• 解析规则(可选):重命名规则、类的解析/忽略 等…
• BridgeSupport文件(必需):类、方法、函数、结构信息
• 补充文件(Objective – CGON):继承结构、协议和属性信息

“glue” code generation

配置规则

有一套强大的配置规则可以转换本地API到自定义的JS API。让我们看看其中一些规则.

重命名规则:
重命名规则允许我们重命名方法名,类名,函数名或结构名。下面示例代码默认的JS API:

// CCAnimation (from cocos2d-iphone v2.0)+(id) animationWithAnimationFrames:(NSArray*)arrayOfAnimationFrames delayPerUnit:(float)delayPerUnit loops:(NSUInteger)loops;

将是:

// uglycc.CCAnimation.animationWithAnimationFrames_delayPerUnit_loops_( frames, delay, loops );

我们可以利用一套简单的规则把这个JS API命名为如下所示的函数:

// more JS friendlycc.Animation.create( frames, delay, loops );

为了做到这一点,我们要把前缀CC从类名中移除, 因为它已经使用了名为cc的JS名字空间。
obj_class_prefix_to_remove = CC
最后,我们添加一个方法的命名规则:
method_properties = CCAnimation # animationWithAnimationFrames:delayPerUnit:loops: = name:”create”,

合并规则:
但是CCAnimation的其它构造函数会发生什么呢?

// CCAnimation supports 4 different constructors+(id) animationWithSpriteFrames:(NSArray*)arrayOfSpriteFrameNames;+(id) animationWithSpriteFrames:(NSArray*)arrayOfSpriteFrameNames delay:(float)delay;+(id) animationWithAnimationFrames:(NSArray*)arrayOfAnimationFrames delayPerUnit:(float)delayPerUnit loops:(NSUInteger)loops;

我们应该做的是创建一个规则,把四个构造函数合并为一个。JSB会根据参数的个数正确 执行. 这个规则如下所示:
method_properties = CCAnimation # animationWithAnimationFrames:delayPerUnit:loops: = name:”create”; merge: “animation” | “animationWithSpriteFrames:” | “animationWithSpriteFrames:delay:”,

JS的代码将看起来像这样:

// calls [CCAnimation animation]var anim = cc.Animation.create();// calls [CCAnimation animnationWithSpriteFrames:]var anim = cc.Animation.create(array);// calls [CCAnimation animnationWithSpriteFrames:delay:]var anim = cc.Animation.create(array, delay);// calls [CCAnimation animationWithAnimationFrames:delayPerUnit:loops:]var anim = cc.Animation.create(array, delay, loops);

回调规则:
JSB支持回调方法,为了把一个函数注册为回调函数,你需要在配置文件中添加一条回调 规则. 例如:
method_properties = CCNode#onEnter = callback,

你也可以重命名回调函数:
method_properties = CCLayer # ccTouchesBegan:withEvent: = callback; name:”onTouchesBegan”,

示例配置:
进一步学习了解配置文件, 可参考下面的例子。

• cocos2d_jsb.ini
• CocosDenshion_jsb.ini
• chipmunk_jsb.ini
• CocosBuilderReader_jsb.ini

 

JS Bingdings内幕(“胶水”代码)

JS代码绑定允许本地代码和JS代码互相调用。让我们来看看细节:

JS调用本地函数
下面的代码将调用本地C函数ccpAdd():

var p1 = cc.p(0,0);var p2 = cc.p(1,1);// cc.pAdd is a "wrapped" function, and it will call the cocos2d ccpAdd() C functionvar ret = cc.pAdd(p1, p2);

让我们看看本地ccpAdd的声明

CGPoint ccpAdd(const CGPoint v1, const CGPoint v2);

当执行cc.pAdd时,它会调用“粘合剂”的功能代码JSB_ccpAdd。JSB_ccpAdd做了以下事情:

• 把JS参数转换为本地参数
• 调用本地的ccpAdd()函数
• 把本地的返回值转换成JS的返回值
• 转换参数或返回值时 如果遇到错误,则失败

function call flow

JS调用本地实例/类方法
可以从JS调用实例或类的方法。内部逻辑和调用本机函数相似。让我们来看看:

//创建一个精灵并设置其位置为200,200var sprite = cc.Sprite.create('image.png');sprite.setPosition( cc.p(200,200) );cc.Sprite.create("image.png")

将调用“胶水”函数
JSB_CCSprite_spriteWithFile_rect__static
做了以下事情:

• JS字符串转换成本地字符串
• 通过调用 [CCSprite spriteWithFile:@"image.png"]创建一个本地实例
• 本地实例转换成JS对象
• 新创建的实例添加到字典,使用JS对象作为key
• 返回转换后的JS实例

sprite.setPosition(cc.p(200,200)) 将调用“胶水”函数JSB_CCNode_setPosition_,
做了以下事情:

• 通过JS对象作为key,从字典中获取本机实例。
• JS对象转换成CGPoint
• 调用[instance setPosition:p]
• setPosition没有返回值,它返回一个“void”对象给JS

class instantiation flow

instance method flow

从本地调用JS代码
回调函数
可以生成两种类型的回调:

• 在JS中触发回调而在本地执行(前面提到过)
• 在本地触发回调并执行JS代码。也就是所谓的”回调”

例如,cocos2d-iphone的onEnter,onExit,update回调函数。onEnter在本地触发,JS中 可重写这个方法. 在下面这个例子里,JS函数onEnte会被本地代码调用:

var MyLayer = cc.Layer.extend({ctor:function () {cc.associateWithNative( this, cc.Layer );this.init();},onEnter:function() {cc.log("onEnter called");},});

JSB支持回调,且不需要修改被解析库的源代码。JSB要做的是,把原始回调方法和JSB回调方法交换。

完整的流程:

• JSB注册所有交换方法为回调
• 在交换方法调用时:
  *调用本地回调函数
  *然后调用JS回调函数(如果有)

callbacks flow

脚本执行:

本地代码调用JS脚本,方法如下:

// JSBCore is responsible registering the native objects in JS, among other thingsif( ! [[JSBCore sharedInstance] runScript:@"my_js_script.js"] )  NSLog(@"Error running script");

谁在使用JSB?
JSB已成功应用于下列开源项目:

• cocos2d-iphone v2.1 (develop-v2 branch): 2d game engine for iOS             
• CocosDenshion: The sound engine bundled with cocos2d
• CocosBuilder Reader: A reader for the cocos2d world editor
• Chipmunk Physics: 2d rigid body physics engine

cocos2d-iphone的开发分支有3个demo工程使用了JSB:

• JS Tests: cocos2d JS bindings tests
• JS Watermelon With Me: a simple physics game that uses JS bindings for cocos2d, Chipmunk, CocosDenshion and CocosBuilder Reader.
• JS MoonWarriors: A top-down shooter that uses JS bindings for cocos2d

值得一提的是,得益于一套强大的规则,cocos2d-iphone生成的JS API和
cocos2d-HTML5 API是相同的。
Moon Warriors 可以使用cocos2d­iphone+JSB 或 cocos2d­html5运行,无需修改一行代码. 试试web版本:Moon Warriors Web
Bugs/局限性
这篇博章时,JSB有下面的bugs或局限。最新清单请访问JSB Homepage.

• 没有JS调试器。SpiderMonKey 15发布后,会添加远程调试功能。
• 没有JS分析工具
• 本地对象控制JS对象的生命周期
  这意味着本机对象被释放了,而JS对象仍然存在。
  在某些情况下JS对象可能指向一个已经被释放的本机对象, 从而产生逻辑错误。
• 回调函数不支持返回值. 支持参数有限。
• 脚本无法解析BridgeSupport常量。
• 避免使用OS X 10.6(或更老)系统的gen_bridge_metada。建议使用OS X 10.8(Mountain Lion)的gen_bridge_metada来生成BridgeSupport文件。
• 从头做一个新项目是不容易的。Xcode模板即将来临。在此之际,更简单的方法就是通过复制JS“targets”来绑定cocos2d-iphone v2.1。