实现球体碰撞，使用这个库就够了

一、简述

大家在用Canvas实现球体碰撞的动画场景时是否感觉无从下手，或者是知道怎么去实现，但是要进行大量的计算，考虑非常多的细节，比如要考虑将外力分解为水平和垂直两个方向，然后考虑各种碰撞的检测，发生重叠后的修正，还有可能考虑引力方向和大小、透明度渐变等等这些，思考这些个计算逻辑时真的很让人头大，今天我就和大家分享一个非常好用的库，一个专门用于在Canvas上实现球体碰撞和球体交互场景的库–sphere-collision，通过简单配置便可快速实现碰撞效果，而且还提供了钩子函数，扩展性极强，让你实现想要的效果。

二、案例展示

下面展示几个案例的实现效果，这些都是使用这个库实现的动画效果，只要涉及到球体碰撞或球体交互的场景都可以使用这个库。

1.探照灯效果

2.球体碰撞交互效果

3.消灭行星小游戏

4.各类球体自由落体交互效果

5. 炫酷倒计时动画

以上案例源码均在visualization-collection开源项目中，github地址：https://github.com/hepengwei/visualization-collection

三、基本用法

安装

npm i sphere-collision

使用

import SphereCollision from "sphere-collision";

const canvasWidth = 600; // 画布宽度
const canvasHeight = 600; // 画布高度
const globuleRadius = 60; // 球半径

const beforeDrawGlobules = (sphereCollision) => {
    const { ctx } = sphereCollision;
    // 绘制整个画布的背景色
    ctx.clearRect(0, 0, canvasWidth, canvasHeight);
    ctx.beginPath();
    ctx.fillStyle = "#000000";
    ctx.fillRect(0, 0, canvasWidth, canvasHeight);
};

const canvas = document.getElementById("myCanvas");
if (canvas) {
    canvas.width = canvasWidth;
    canvas.height = canvasHeight;
    const ctx = canvas.getContext("2d");

    // 实例化SphereCollision对象
    const sphereCollision = new SphereCollision(
        ctx,
        canvas,
        [
            {
                initX: 400,
                initY: 400,
                vx: 6,
                vy: 3,
                radius: globuleRadius,
            },
        ],
        { beforeDrawGlobules }
    );

    // 开使执行动画
    sphereCollision.start();
}

四、API文档

SphereCollisionC

参数（顺序从上往下依次传入）	数据类型	说明	默认值	是否必需
ctx	CanvasRenderingContext2D	Context对象	null	是
canvas	HTMLCanvasElement	Canvas对象	null	是
globuleOptionsList	GlobuleOptions[]	初始化球体的配置列表	[]	否
options	SphereCollisionOptions	配置参数	SphereCollisionOptions	否
属性
ctx	CanvasRenderingContext2D	Context对象
canvas	HTMLCanvasElement	Canvas对象
frameId	number	requestAnimationFrame方法返回的ID
globuleList	GlobuleC[]	保存所有球体实例的列表
animationState	enum AnimationState{“waitStart”,“inAnimation”,“stop”}	当前动画状态
mousePos	MousePos	当前鼠标在Canvas中的位置坐标
prevMousePos(v1.1.0新增)	MousePos	前一次鼠标在Canvas中的位置坐标
isMouseDown(v1.1.0新增)	boolean	当前鼠标在Canvas中是否按下
mouseDownPos(v1.1.0新增)	MousePos	鼠标在Canvas中按下时的位置坐标
mouseInGlobuleList(v1.1.0新增)	GlobuleC[]	当前鼠标所在球体中的球体实例列表
方法
start	() => void	必须调用该方法，Canvas才渲染，开始执行相关动画
createGlobule	(globuleOptions: GlobuleOptions) => Globule	创建球体实例的方法
updateGlobuleList	(newGlobuleList: GlobuleC[]) => void	更新球体实例列表，用于动态增加或减少球体实例
stop	() => void	停止整个frame动画

GlobuleOptions

属性	数据类型	说明	默认值	是否必需
id	any	任意值，可存放数据		否
initX	number	初始x坐标（向右为正方向）	0	否
initY	number	初始y坐标（向下为正方向）	0	否
vx	number	在水平方向的速度（向右为正方向）	0	否
vy	number	在垂直方向的速度（向下为正方向）	0	否
radius	number	半径	10	否
color	string	颜色	“#666666”	否
isPureColor(v1.1.3新增)	boolean	是否为纯色	false	否
alpha	number	透明度	1	否
alphaChangeV	number	透明度改变的速度（正数增加，负数减小）	0	否
bgImg	string	背景图片	“”	否
collisionLossV	number	碰撞时的速度损失	0	否
moveLossV	number	移动时的速度损失	0	否
gDirection	“toInit” | “toBottom” | “toTop” | “toLeft” | “toRight”	引力方向。“toInit”，指向球体的初始位置；“toBottom”，指向正下方；“toTop”，指向正上方；“toLeft”，指向正左方；“toRight”，指向正右方(后四个为v1.1.0新增)		否
gCoefficient	number	引力系数	0	否
requiredMouseInteraction	boolean	是否需要鼠标交互	false	否
mouseInteractionBehavior(v1.1.0新增)	“over” | “drag”	鼠标交互行为。“over”，鼠标穿过；“drag”，鼠标拖拽	当requiredMouseInteraction为true时，默认值为"over"，当为false时，则没有默认值	否
fixedPos	boolean	是否固定位置	false	否
receiveOutForce	boolean	是否接受外力	true	否
receiveWallForce	boolean	是否接受墙的力（与墙体发生碰撞）	true	否
resistanceWallDirection(v1.1.3新增)	Direction[]	有阻力的墙的方向	[“bottom”, “top”, “left”, “right”]	否
onlyCheckCollision	boolean	当不接受外力时，是否检测碰撞（检测碰撞相关状态但不获取外力）	false	否
perfectlyElasticCollision(v1.1.10 新增)	boolean	是否完全弹性碰撞	false	否
maxMouseOutForce	number	鼠标交互时能提供的最大力限制	null	否
maxMoveV	number	最大移动速度	null	否
beforeDrawGlobule	(globule: GlobuleC) => void	每一帧绘制该球体之前执行的钩子函数	null	否
afterDrawGlobule	(globule: GlobuleC) => void	每一帧绘制该球体之后执行的钩子函数	null	否
afterCalculateNextFrameGlobule	(nextFrameGlobule: GlobuleC) => void	每一帧绘制球体后,计算并修改为下一帧状态后执行的钩子函数	null	否

SphereCollisionOptions

属性	数据类型	说明
collisionRectX	number	球体发生碰撞的矩形区域的左上角x坐标（向右为正方向）	0	否
collisionRectY	number	球体发生碰撞的矩形区域的左上角y坐标（向下为正方向）	0	否
collisionRectWidth	number	球体发生碰撞的矩形区域的宽度	canvas.width	否
collisionRectHeight	number	球体发生碰撞的矩形区域的高度	canvas.height	否
monitorMousePos	boolean	是否监听鼠标的位置	false	否
beforeDrawGlobules	(sphereCollision: SphereCollisionC) => void	每一帧绘制所有球体之前执行的钩子函数	null	否
afterDrawGlobules	(sphereCollision: SphereCollisionC) => void	每一帧绘制所有球体之后执行的钩子函数	null	否
onMouseDownCanvas(v1.1.0新增)	(event: MouseEvent, sphereCollision: SphereCollisionC) => void	鼠标按下时执行的钩子函数	null	否
onMouseMoveCanvas(v1.1.0新增)	(event: MouseEvent, sphereCollision: SphereCollisionC) => void	鼠标移动时执行的钩子函数	null	否
onMouseUpCanvas(v1.1.0新增)	(event: MouseEvent, sphereCollision: SphereCollisionC) => void	鼠标松开时执行的钩子函数	null	否
onMouseLeaveCanvas(v1.1.0新增)	(event: MouseEvent, sphereCollision: SphereCollisionC) => void	鼠标离开时执行的钩子函数	null	否

MousePos

属性	数据类型	说明
mouseX	number | null	鼠标在Canvas中的x坐标（向右为正方向）
mouseY	number | null	鼠标在Canvas中的y坐标（向下为正方向）

Direction

属性	数据类型	说明
Direction	“bottom” | “top” | “left” | “right”	方向

GlobuleC

属性	数据类型	说明
id	any	任意值,可存放数据
ctx	CanvasRenderingContext2D	Context对象
canvas	HTMLCanvasElement	Canvas对象
requiredMouseInteraction	boolean	是否需要鼠标交互
mouseInteractionBehavior(v1.1.0新增)	“over” | “drag”	鼠标交互行为。“over”，鼠标穿过；“drag”，鼠标拖拽
maxMouseOutForce	number | null	鼠标交互时能提供的最大力限制
initX	number	初始x坐标（向右为正方向）
initY	number	初始y坐标（向下为正方向）
x	number	x坐标（向右为正方向）
y	number	y坐标（向下为正方向）
previousX(v1.1.8 新增)	number | null	前一帧 x 坐标（向右为正方向）
previousY(v1.1.8 新增)	number | null	前一帧 y 坐标（向右为正方向）
vx	number	在水平方向的速度（向右为正方向）
vy	number	在垂直方向的速度（向下为正方向）
radius	number	半径
color	string	颜色
isPureColor(v1.1.3新增)	boolean	是否为纯色
alpha	number	透明度
alphaChangeV	number	透明度改变的速度（正数增加，负数减小）
bgImg	string	背景图片
collisionLossV	number	碰撞时的速度损失
moveLossV	number	移动时的速度损失
gDirection	“toInit” | “toBottom” | “toTop” | “toLeft” | “toRight”	引力方向。“toInit”，指向球体的初始位置；“toBottom”，指向正下方；“toTop”，指向正上方；“toLeft”，指向正左方；“toRight”，指向正右方(后四个为v1.1.0新增)
gCoefficient	number	引力系数
fixedPos	boolean	是否固定位置
receiveOutForce	boolean	是否接受外力
receiveWallForce	boolean	是否接受墙的力（与墙体发生碰撞）
resistanceWallDirection(v1.1.3新增)	Direction[]	有阻力的墙的方向
onlyCheckCollision	boolean	当不接受外力时，是否检测碰撞（检测碰撞相关状态但不获取外力）
perfectlyElasticCollision(v1.1.10 新增)	boolean	是否完全弹性碰撞
mousePos	MousePos	鼠标相对于canvas的位置坐标
maxMoveV	number | null	最大移动速度
controlledByMouse(v1.1.0新增)	boolean	当前是否受鼠标控制(被鼠标拖拽)
inCollisionGlobule	boolean	是否与其他球体发生碰撞的状态
inCollisionGlobuleList	GlobuleC[]	与其他球体碰撞的其他球体实例列表
inCollisionWall	boolean	是否与墙体发生碰撞的状态
beforeDrawGlobule	(globule: GlobuleC) => void | null	每一帧绘制该球体之前执行的钩子函数
afterDrawGlobule	(globule: GlobuleC) => void | null	每一帧绘制该球体之后执行的钩子函数
afterCalculateNextFrameGlobule	(nextFrameGlobule: GlobuleC) => void | null	每一帧绘制球体后,计算并修改为下一帧状态后执行的钩子函数
方法
addOutForce	(outForceVX: number, outForceVY: number, isCollision?:boolean = false) => void	添加外力。用于动态增加或减小球体的速度

五、特别说明

• 球体的fixedPos属性为true时， 获取不了外力，所以球体不会移动，但还是会使其他球体受到外力，进行反弹。
• 球体的receiveOutForce属性为false时，获取不了鼠标穿过和其他球体碰撞产生的外力，即使另一个球体的receiveOutForce属性为true。
• 球体的receiveWallForce属性为false时，获取不了来自墙体的外力，所以不会与墙体发生碰撞。
• 球体的beforeDrawGlobule和afterDrawGlobule两个钩子函数，主要作用是在绘制球体之前和之后分别去绘制其他元素，而afterCalculateNextFrameGlobule钩子函数是用于做一些其他的逻辑判断，因为只有这个函数里拿到的球体实例是带有是否发生碰撞等相关信息的
• 如果实例化SphereCollision对象时传入了beforeDrawGlobules钩子函数，并且需要在每一帧绘制前要清除整个画布，则需要使用者自己清除，这是考虑到有些不需要清除的场景。
• 如果要获取鼠标相关的信息或者想要实现鼠标交互，实例化SphereCollision对象时就必须在第四个参数options中传入monitorMousePos为true。
• 如果给球体配置了 gDirection 和 gCoefficient 属性，建议就不要配置 collisionLossV 了。
• 非完全弹性碰撞会有速度的抵消，可能碰撞后的 x 轴或 y 轴方向上的速度相互抵消为 0，球体可能会停下来；完全弹性碰撞则不会有速度的抵消，速度大小不会改变(速度为 0 除外，速度为 0 的，碰撞后会和撞它的另一球的速度大小一致)，碰撞后仅改变方向; 在碰撞时如果其中有一个球体的 perfectlyElasticCollision 为 true，则两球均使用完全弹性碰撞算法进行计算。
• 如果需要的话，可以在任何时候动态地修改球体实例的所有属性值，以满足自己的自定义需求。

六、关键版本更新日志

• v1.1.10

1. 新增支持球体完全弹性碰撞
2. 优化代码
   
   

• v1.1.8

1. 优化碰撞算法
2. 解决一些已知bug
   
   

• v1.1.3

1. 新增支持纯色球体
2. 新增支持四面墙中只有部分墙面有阻力，与球体发生碰撞
3. 解决一些已知bug
   
   

• v1.1.0

1. 考虑后续的功能扩展，修改了SphereCollision类的参数，将之前的第四个及之后的参数都统一放到options对象中，并作为第四个参数传入。
2. 新增支持上下左右四个引力方向
3. 新增支持球体进行鼠标拖拽交互
4. 新增的相关属性及方法可自行查阅API文档
   
   

更多个人文章

1. 两个跨域页面进行跳转传参的终极方案
2. 彻底搞懂盒子模型
3. hashHistory和browserHistory的区别
4. 十分钟带你入门Chrome插件开发
5. 面试秘籍之排序算法