通用API

通用模块(Utils)

全局常量

脚本环境常量

常量

类型

描述

Utils.netMode

NetMode

见描述

若当前脚本为服务端环境,值为NET_MODE_SERVER

若当前脚本为客户端环境,值为NET_MODE_CLIENT

数学常量

常量

类型

描述

Utils.E

double

2.71828175

自然常数

Utils.LOG2E

double

1.442695

以 2 为底 e 的对数

Utils.LOG10E

double

0.4342945

以 10 为底 e 的对数

Utils.PI

double

3.14159274

圆周率

Utils.TWO_PI

double

6.28318548

圆周率 x 2

Utils.PI_OVER_2

double

1.57079637

圆周率 / 2

Utils.PI_OVER_4

double

0.7853982

圆周率 / 4

随机数

函数

返回值

描述

Utils.RandInt(int n)

int

若n大于0,返回[0, n)的随机整数,否则返回0。

Utils.RandIntArea(int begin, int len)

int

若len大于0,返回[begin, begin + len)的随机整数,否则返回begin。

Utils.RandDouble(double value)

double

若value大于0,返回[0, value)的随机浮点数,否则返回0。

Utils.RandDoubleArea(double begin, double len)

double

若len大于0,返回[begin, begin + len)的随机浮点数,否则返回begin。

Utils.RandSym(double value)

double

返回(-value, value)的随机浮点数。

Utils.RandTry(int n)

bool

当n为正数时1/n概率返回true,否则始终返回false。

例1:Utils.RandTry(3)有1/3概率返回true。

例2:Utils.RandTry(2)有一半概率返回true。

数学运算与模型

函数

返回值

描述

Utils.Cell(double a)

int

返回实际横/纵坐标对应的格子横/纵坐标。注意每个格子为16像素,实际结果为除以16后向下取整。

Utils.PositiveMod(int a, int b)

int

返回a与b求余的非负数结果。

例1:Utils.PositiveMod(5, 3)返回2。

例2:Utils.PositiveMod(-5, 3)返回1。

Utils.FloorDivide(int a, int b)

int

若b非0,返回a向下取整整除b的结果,否则返回0。

例1:Utils.FloorDivide(10, 3)返回3。

例2:Utils.FloorDivide(-4, 3)返回-2。

Utils.SinValue(int phase, int period, int begin = 0)

double

返回以period为周期、以begin为初相位的正弦波在相位phase的值。

Utils.CosValue(int phase, int period, int begin = 0)

double

返回以period为周期、以begin为初相位的余弦波在相位phase的值。

Utils.ToTargetValue(double start, double target, double step)

double

返回start值往target值方向移动step长度的结果,若到达target值,则返回target值。 例1:Utils.ToTargetValue(1, 10, 5)返回6。 例2:Utils.ToTargetValue(6, 10, 5)返回10。

二维空间几何

函数

返回值

描述

Utils.GetPointsDistance(double x1, double y1, double x2, double y2)

double

返回点(x1, y1)到点(x2, y2)的距离。

例:Utils.GetPointsDistance(1.0,0.0,4.0,4.0)返回5.0。

Utils.GetDistance(double x, double y)

double

返回点(x, y)到原点(0, 0)的距离。

例:Utils.GetDistance(3.0, 4.0)返回5.0。

Utils.GetPointSegmentDistance(double x, double y, double x1, double y1, double x2, double y2)

double

返回点(x, y)到以点(x1, y1)和点(x2, y2)为两端点的线段的距离。

Utils.GetAngle(double x, double y)

double

返回向量(x, y)与横坐标的夹角。

例1:Utils.GetAngle(1, 1)返回π/4。

例2:Utils.GetAngle(0, 1)返回π/2。

Utils.FixAngle(double angle)

double

将角度按2π周期增加或减少,返回最终限定在区间(-π, π]内的结果。

Utils.GetXYFromPolar(double length, double angle)

double, double

将极坐标转换为直角坐标,返回横坐标和纵坐标。

Utils.RotateXY(double x, double y, double angle)

double, double

将点(x, y)绕原点旋转指定角度,返回旋转后的横坐标和纵坐标。

简单物理运动

函数

返回值

描述

Utils.SlowSpeed2D(double speedX, double speedY, double dec)

double, double

将一个二维速度(speedX, speedY)以恒定速度(dec)降低,返回新的横速度和纵速度。

Utils.SlowSpeed1D(double speed, double dec)

double

将一个速度以恒定速度(dec)降低,返回新的速度。

Utils.ForceSpeed2D(double speedX, double speedY, double force, double forceAngle, double maxSpeed)

double, double

将一个二维速度(speedX, speedY)进行受力,返回新的横速度和纵速度。

源码参考

源码均以C++伪代码的形式展示,你可以通过这些源码来理解API的具体功能。

int Utils.PositiveMod(int a, int b)

int c = a % b;
if (c < 0) c += b;
return c;

int Utils.FloorDivide(int a, int b)

return a / b - ((a < 0 && a % b != 0) ? 1 : 0);

double Utils.GetPointsDistance(double x1, double y1, double x2, double y2)

return sqrt(pow((x1)-(x2), 2) + pow((y1)-(y2), 2));

double Utils.GetDistance(double x, double y)

return sqrt(pow(x, 2) + pow(y, 2));

double Utils.GetPointSegmentDistance(double x, double y, double x1, double y1, double x2, double y2)

double cross = (x2 - x1) * (x - x1) + (y2 - y1) * (y - y1);
if (cross <= 0) return sqrt((x - x1) * (x - x1) + (y - y1) * (y - y1));

double d2 = (x2 - x1) * (x2 - x1) + (y2 - y1) * (y2 - y1);
if (cross >= d2) return sqrt((x - x2) * (x - x2) + (y - y2) * (y - y2));

double r = cross / d2;
double px = x1 + (x2 - x1) * r;
double py = y1 + (y2 - y1) * r;
return sqrt((x - px) * (x - px) + (py - y) * (py - y));

double Utils.GetAngle(double x, double y)

return atan2(y, x);

double Utils.FixAngle(double angle)

if (angle >= PI) angle -= 2 * PI * ceil((angle - PI) / (2 * PI));
else if (angle < -PI) angle += 2 * PI * ceil((-angle - PI) / (2 * PI));
return angle;

double Utils.SinValue(int phase, int period, int begin)

return sin(begin + 2 * PI * float(phase % period) / period);

double Utils.CosValue(int phase, int period, int begin)

return cos(begin + 2 * PI * float(phase % period) / period);

double Utils.ToTargetValue(double start, double target, double step)

if (fabs(start - target) < step) start = target;
else if (start > target) start -= step;
else start += step;
return start;

void Utils.GetXYFromPolar(double & x, double & y, double length, double angle)

x = length * cos(angle);
y = length * sin(angle);

void Utils.RotateXY(double & x, double & y, double angle)

double dx = x, dy = y;
x = dx * cos(angle) - dy * sin(angle);
y = dx * sin(angle) + dy * cos(angle);

void Utils.SlowSpeed2D(double & spx, double & spy, double dec)

double moveAngle = ut.getAngle(spx, spy);
spx = ut.toTargetValue(spx, 0, cos(moveAngle)*dec);
spy = ut.toTargetValue(spy, 0, sin(moveAngle)*dec);

double Utils.SlowSpeed1D(double speed, double dec)

return ut.toTargetValue(speed, 0, dec);

void ForceSpeed2D(double & spx, double & spy, double force, double forceAngle, double maxSpeed)

double forceX = force * cos(forceAngle);
double forceY = force * sin(forceAngle);
spx += forceX;
spy += forceY;
double moveAngle = GetAngle(spx, spy);
double maxSpx = maxSpeed * cos(moveAngle);
double maxSpy = maxSpeed * sin(moveAngle);

if (maxSpx >= 0) {
	if (spx > maxSpx) spx = maxSpx;
}
else {
	if (spx < maxSpx) spx = maxSpx;
}
if (maxSpy >= 0) {
	if (spy > maxSpy) spy = maxSpy;
}
else {
	if (spy < maxSpy) spy = maxSpy;
}

Last updated