C++精灵库 Sprite（角色/精灵）类方法教程。本教程已内置于pxC++编辑器。
在C++精灵库中有两大类型，一个是Screen(屏幕)类，另一个就是Sprite(角色)类。Sprite类用于实例化一个角色。角色藏有一只看不见的画笔。用户可以通过角色的方法对画笔进行设定。如画笔颜色、线宽、填充颜色。角色可以前进、倒退、左转、右转、变大变小等等。用户通过符合逻辑的代码组合，不仅能画出漂亮的图案，还能制作动画与交互作品。在C++精灵库中,画笔的颜色最终由r,g,b,a值决定。所有通过设定颜色的色相、饱和度、明度最终都会转换为RGBA值。并且在规定色相的取值范围是0到360，而饱和度和明度的取值范围是0.0到100.0。至于画笔的shade值，它是一个综合的值，用于描述色彩的深浅度。shade值为0时表示颜色最深，值为100时表示颜色最浅(白色)。
1. Sprite (角色类的构造函数名)
作用: 创建一个角色对象，自动地关联到第一个新建立的屏幕,如果没有新建屏幕对象,则会自动建立一个,以后手动建立的屏幕对象无效。
用法:
Sprite rocket; //创建一个叫rocket角色，选型默认是一枚小火箭。
Sprite t(“turtle”); //创建一个叫t的角色，造型是海龟,自动关联到”res/turtle.png”图片为造型。
Sprite t(“blank”); //创建一个叫t的角色，没有造型。
Sprite t{“res/turtle.png”}; //创建一个叫t角色，造型是res目录下面的turtle.png图片。
Sprite turtle({“res/turtle_red.png”,”res/turtle_blue.png”}); //创建一个叫turtle角色，它有两个造型。
Sprite t{“turtle”,false,”object”,100,100,45}; //turtle造型、可见性、标签、x坐标、y坐标、朝向。
Sprite* haigui = new Sprite(“turtle”); //新建turtle造型的角色，返回地址赋值给haigui。
haigui->fd(200); //由于haigui是指针，所以要用->号来调用fd方法。
移动与方向控制
2. forward / fd
作用: 向当前朝向前进指定距离。sprite表示角色的名字,下同。
用法: sprite.fd(50);
返回对角色的引用。
3. backward / back / bk
作用: 向当前朝向后退指定距离。
用法: sprite.bk(30);
返回对角色的引用。
4. right / rt
作用: 向右旋转指定角度（顺时针）。
用法: sprite.rt(90); // 右转90度
返回对角色的引用。
5. left / lt
作用: 向左旋转指定角度（逆时针）。
用法: sprite.lt(45); // 左转45度
返回对角色的引用。
6. setheading / seth
作用: 设置角色的绝对朝向（0° 为正右方，90° 为正上方）。
用法: sprite.seth(0); // 面向右
返回对角色的引用。
7. heading
作用: 朝向某个角色(坐标点)或者获取角色当前的朝向角度（0~360）。
用法: float angle = sprite.heading(); //得到角色的方向值
sprite.heading(100,100); //让角色朝向(100,100)的方向
当有参数时，返回对角色的引用。
举例:
#include “sprites.h” //包含C++精灵库
Sprite rocket; //建立角色叫rocket
Sprite t;
int main(){ //主功能块
rocket.penup().speed(0).go(100,100);
t.color(“#ff0000”).speed(0).fd(100) ;
while(g_screen->exitonclick()){
rocket.heading(t); //朝向t的方向
t.circle(100,1); //画半径为100的圆弧，左转1度
}
return 0;
}
8. towards
作用: 计算并返回从角色当前位置指向 (x, y) 点的角度。
用法: float angle = sprite.towards(100, 200);
画笔控制
9. isdown
作用: 判断画笔是否处于“落下”状态（即移动时会画线）。
用法: bool drawing = sprite.isdown();
10. penup / pu / up
作用: 抬起画笔，移动时不画线。
用法: sprite.penup();
返回对角色的引用。
11. pendown / pd / down
作用: 落下画笔，移动时会画线。
用法: sprite.pendown();
返回对角色的引用。
12. pensize / width
作用: 设置或获取画笔的粗细（像素）。
用法:
sprite.pensize(5);
int w = sprite.pensize();
加参数时返回对角色的引用。
13. pencolor
作用: 设置画笔颜色（支持字符串、RGB、HSV 等多种格式）。
用法:
sprite.pencolor(“#ff0000”);
sprite.pencolor(“red”);
sprite.pencolor(255, 0, 0); // RGB形式
sprite.pencolor(0); // 设置HSV色相为0(红),同时设置饱和度和明度最大，注意和penhue的区别。
加参数时返回对角色的引用。
不加参数时返回字符串形式的画笔颜色。
14. penhue / pensat(penbhd) / penvalue / penshade
背景: C++精灵库规定画笔颜色默认的色相、饱和度、明度初始值都是0。至于shade值，是一个综合的值。关于hsv颜色模式，请先查阅相关资料学习。
作用: 分别设置画笔颜色的色相(Hue,0到360)、饱和度(Saturation,0.0到100.0)、明度(value,0到100)、色彩的深浅度(Shade,0到100)。
用法: sprite.penhue(120); // 只设置颜色的色相，这里120是绿色，注意和pencolor(120)的区别。如果此时明度为0，则是黑色。
返回对角色的引用。
举例:
#include “sprites.h” //包含C++精灵库
Sprite rocket; //建立角色叫rocket
int main(){ //主功能块
rocket.penup().speed(0).bk(180).pensize(20);
rocket.bgcolor(“black”).pendown();
//pencolor(0)设定色相为0(红色)同时设定饱和度和明度最大(100)
rocket.pencolor(0);
//只设定色相 ,hsv中的hue值
for(int h = 0;h<=360;h++)
rocket.penhue(h).fd(1);
rocket.pu().addy(60).bk(360).pd();
//只设定饱和度 ,hsv中的saturation值
for(int h = 0;h<=100;h++)
rocket.pensat(h).fd(2);
rocket.pu().addy(60).bk(200).pd();
//只设定明度 ,hsv中的v值
for(int v = 0;v<=100;v++)
rocket.penvalue(v).fd(2);
rocket.pu().addy(60).bk(200).pd();
//只设定色彩的深浅度 ，shade是一个综合的值
for(int sd = 0;sd<=100;sd++)
rocket.penshade(sd).fd(2);
rocket.done();
return 0;
}
15. penhsv
作用: 设置角色画笔的色相、饱和度和明度。
在C++精灵库中，规定的色相值范围是0到360，饱和度和明度的值范围是0到100。
用法: sprite.penhsv(0); //设置画笔的色相为0，饱和度和设调默认最大(100)。
用法: sprite.penhsv(0,50,50); //设置画笔为红色，饱和度为50，明度也是50
返回对角色的引用。
举例:
#include “sprites.h” //包含C++精灵库
Sprite rocket; //建立角色叫rocket
int main(){ //主功能块
rocket.speed(0).pu().bk(180).pensize(20).pd();
for(int i=0;i<360;i++)
rocket.penhsv(i).fd(1);//色相变大，饱和度和明度都是100
rocket.pu().bk(360).addy(50).pd();
for(int i=0;i<=100;i++)
rocket.penhsv(0,i,100).fd(2);//饱和度变大，越来越鲜艳
rocket.pu().bk(200).addy(50).pd();
for(int i=0;i<=100;i++)
rocket.penhsv(0,100,i).fd(2); //明度变大，亮度越来越亮
rocket.done();
return 0;
}
16. coloradd
作用: 颜色的色相增加（用于动态变色）。
用法: sprite.coloradd(1);
返回对角色的引用。
17. coloralpha / penalpha
作用: 设置画笔颜色的透明度（0~255，0 为完全透明）。其本质是设定画笔颜色的RGBA的alpha通道值。
用法: sprite.penalpha(128);
返回对角色的引用。
18. fillcolor
作用: 设置填充颜色（用于 begin_fill/end_fill方法）。
用法: sprite.fillcolor(“blue”);
加参数时返回对角色的引用。
不加参数时返回字符串形式的填充颜色。
19. filling
作用: 判断当前是否处于填充模式（即是否已调用 begin_fill 但未调用 end_fill）。
用法: bool inFill = sprite.filling();
20. begin_fill / end_fill
作用: 开始/结束一个填充区域。两者之间的所有绘图路径将被 fillcolor 填充。
用法:
sprite.begin_fill();
sprite.circle(50);
sprite.end_fill();
角色的begin_fill命令会返回对角色的引用。
角色的end_fill方法会返回路径的顶点向量(列表)
21. dot
作用: 在当前位置绘制一个实心圆点，size是直径。如果不指定color，则使用画笔颜色。
用法: sprite.dot(20, “green”);
返回对角色的引用。
22. circle
作用:
circle: 绘制完整圆形、弧形。
用法:
sprite.circle(30); //逆时针画半径为30的圆圈子
sprite.circle(50, 180); // 逆时针画半径为50的半圆
sprite.circle(-50, 180); // 顺时针画半圆
返回对角色的引用。
23. ellipse/oval
作用: 绘制椭圆（a 为长半轴，b 为短半轴）。
用法: sprite.ellipse(50, 30);
返回对角色的引用。
位置与坐标
24. home
作用: 将角色移回原点 (0, 0) 并重置朝向为 0°。
用法: sprite.home();
返回对角色的引用。
25. go / goxy / gotoxy / setxy / setpos / setposition
作用: 将角色移动到指定坐标 (x, y)。
用法: sprite.gotoxy(100, -50);
返回对角色的引用。
举例:
#include “sprites.h” //包含C++精灵库
Sprite rocket; //建立角色叫rocket
int main(){ //主功能块
rocket.speed(0).go(100,200);
Sprite t(“turtle”); //新建海龟造型角色情
t.go(rocket).wait(0.5);//t到达rocket的位置
Point p0 = {-100,0}; //新建坐标点
t.go(p0).home(); //t到达p0又回家了
rocket.done();
return 0;
}
26. move
作用: 相对当前位置在水平方向移动dx,在垂直方向移动dy。
用法: sprite.move(10, 20);
返回对角色的引用。
27. xcor / ycor / position / pos
作用: 获取角色的 X 坐标、Y 坐标或位置。
用法:
float x = sprite.xcor(); //获取x坐标
std::pair<float,float> p = sprite.pos(); //获取坐标
28. setx / gox / gotox
作用: 仅设置 X 坐标，Y 不变。
用法: sprite.setx(100);
返回对角色的引用。
29. sety / goy / gotoy
作用: 仅设置 Y 坐标，X 不变。
用法: sprite.sety(-30);
返回对角色的引用。
30. addx / addy
作用: 在当前 X/Y 坐标上增加偏移量。
用法: sprite.addx(5);
返回对角色的引用。
31. distance
作用: 计算角色当前位置到(x, y) 或其它角色的欧氏距离。
用法: float d = sprite.distance(0, 0);
//下面的bug是另一个角色的名称
用法: float d = sprite.distance( bug );
外观与造型
32. get_width / get_height
作用: 获取角色缩放后造型的原始宽高。
用法: int w = sprite.get_width();
33. scale 或 shapesize 变形命令
作用:
scale: 统一设置 X/Y 方向的缩放比例。
shapesize: 分别缩放。
用法:
sprite.scale(2.0);
sprite.shapesize(0.5,2.0);
加参数时返回对角色的引用。
不加参数时返回水平与垂直方向上的缩放比例，存储的数据结构是：std::pair<double,double> 。
34. addshape
在Sprite类中有私有的shapeslist向量，用于记录索引到造型图片路径的映射，有shapesdict(字典)用于记录造型图片路径到Shape的映射。Shape是一个纹理的包装类，如果对这些不懂，请忽略。
作用: 动态添加一个造型（图片）。
用法: sprite.addshape(“res/hero.png”); //添加造型
返回对角色的引用。
35. removeshape
作用: 移除一个造型
用法: sprite.removeshape(“res/hero.png”); //移去这个造型
用法: sprite.removeshape(0); //移去造型列表中索引为0的造型
36. next_costume / nextcostume / pre_costume / precostume
作用: 切换到下一个或上一个造型（用于动画）。
用法: sprite.nextcostume();
返回对角色的引用。
37. shape
作用: 切换到当前path指定图片为角色造型。
用法: sprite.shape(“idle.png”); //根据图片路径切换到此造型
用法: sprite.shape(0); //切换到索引为0的造型
用法: std::cout << sprite.shape(); //返回造型图片路径
shape方法返回对角色的引用。
38. shapeindex()
作用: 返回当前造型的索引号。
用法: std::cout << sprite.shapeindex(); //返回当前造型的索引号。
39. shapes
作用: 返回角色的造型数量。
用法: int amounts = sprite.shapes();
40. show / hide
作用: 显示/隐藏角色，show的别名是st，hide的别名是ht。
用法: sprite.show(); //显示角色
用法: sprite.st(); //显示角色
用法: sprite.hide(); //隐藏角色
用法: sprite.ht(); //隐藏角色
返回对角色的引用。
41. isvisible / ishide
作用: 判断角色是否可见 / 是否隐藏
用法: if (sprite.isvisible()) { … } //如果角色是可见的
42. rotate_mode / rotatemode
作用: 设置旋转模式（如 0 自由旋转）。
用法: sprite.rotatemode(0);
返回对角色的引用。
43. rotate_center
作用: 设置角色旋转的中心点（相对于角色原始造型中心点的水平与垂直偏移），同时角色也以这个点为基准坐标。
用法: sprite.rotate_center(0, 0); // 以中心为轴旋转，这是默认的，所以一般不需要设置。
返回对角色的引用。
碰撞与边界
44. bbox
作用: 获取角色在屏幕上的AABB包围盒（SDL_Rect）。
用法: SDL_Rect box = sprite.bbox();
45. contain
作用: 判断点 (cx, cy) 是否在角色的包围盒内。
用法: bool inside = sprite.contain(mouse_x, mouse_y);
46. rect_collide
作用: 检测与另一个角色 other 是否发生矩形碰撞。
用法: if (sprite.rect_collide(&enemy)) { … }
47. bounce_on_edge
作用: 如果角色碰到屏幕边缘，则自动反弹（改变朝向）。
用法: 在游戏循环中调用 sprite.bounce_on_edge();
返回对角色的引用。
图章（Stamp）
48. stamp
作用: 在当前位置“盖章”，留下角色当前造型的静态图像。
用法: sprite.stamp();
返回图章编号，注意，无法继续链式调用。
49. clearstamp / clearstamps
作用:
clearstamp: 清除指定 ID 的图章。
clearstamps: 清除部分或者所有图章。
用法: sprite.clearstamps();
都返回对角色的引用。
举例:
#include “sprites.h” //包含C++精灵库
Sprite rocket; //建立角色叫rocket
int main(){ //主功能块
for(int i=0;i<10;i++)
rocket.fd(30).stamp();
rocket.clearstamps(3); //清除最早盖的3个图章
rocket.wait(1);
rocket.clearstamps(-3); //清除最晚盖的3个图章
rocket.wait(1);
rocket.clearstamps(); //清除所有图章
rocket.done();
return 0;
}
50. stampitems
作用: 获取所有图章的 ID 列表。
用法: std::vector<Stamp> ids = sprite.stampitems();
高级绘图与填充
51. setpixel / getpixel
作用: 在角色所在窗口屏幕位置上设置/获取像素颜色（注意：不是windows屏幕）。
用法: sprite.setpixel(“white”);
setpixel返回对角色的引用，而getpixel返回的是Color对象。可以通过Color对象的gethex返回颜色的16进制形式的颜色字符串。
举例:
#include “sprites.h” //包含C++精灵库
Sprite rocket; //建立角色叫rocket
int main(){ //主功能块
rocket.hide().pu();
for(int i=0;i<100;i++)
rocket.setpixel(“red”).fd(1);
rocket.go(100,100).dot(33,”blue”);
Color ys = rocket.getpixel();
//输出应该是#0000ff
std::cout << ys.gethex() << std::endl;
rocket.done();
return 0;
}
52. fill
作用: 从角色当前位置开始进行泛洪填充（Flood Fill），填充封闭区域。
用法: sprite.fill(“yellow”); //如果不在封闭区域填充，则会填充整个窗口屏幕。
用法: sprite.fill(“yellow”,20,-50); //相对于角色坐标,右偏移20个单位,下偏移50个单位进行填充。
返回对角色的引用。
53. color
作用: 同时设置角色的画笔与填充颜色，有多种颜色表示方法。
用法: sprite.color(255, 0, 0, 255); //此处用的是r,g,b,a表示法
用法: sprite.color(“red”,”blue”); //画笔颜色为红色，填充颜色为蓝色
加参数时返回对角色的引用，不加参数时返回画笔颜色与填充颜色，数据结构为std::pair<SDL_Color,SDL_Color>。
文本与显示
54. write
作用: 参数分别是字符串: text, 对齐方式: align, 字体样式: font, 倾斜角度: angle)。write命令在角色当前位置书写文本。
参数:
text: 要写的字符串。
align: 对齐方式，”center”或”left”或”right”。
font: 字体信息，如 {“宋体”, “24”, “bold”}。 //注意数字要加双引号，因为用的是vector<string>来保存font信息。
angle: 文字旋转角度。
用法: sprite.write(“Hello!”, “center”, {“Arial”, “18”,”italic”}); //除了italic(斜体)，还有normal(标准)，bold(粗体),underline(下划线),strikethrough(中划线)。
返回对角色的引用。
状态与管理
55. speed
作用: 设置角色移动和绘图的速度（内部可能影响延迟）。
用法: sprite.speed(10);
加参数时返回对角色的引用。
不加参数时返回对角色的“速度”。
56. kill / destroy /isdestroyed
作用: kill是彻底销毁角色，destroy只清除角色占用的大部分内存资源，没有彻底delete它，而isdestroyed是标记角色为“已销毁”，后续可被delete。用new新建的角色才可用kill命令，不要在循环中动态地kill角色，否则会导致野指针产生，导致内存错误。
用法: sprite.destroy(); if (sprite.isdestroyed()) { … }
无返回值。
57. set_tag / get_tag
作用: 为角色设置/获取一个自定义标签（用于分类或识别）。
用法: sprite.set_tag(“player”);
用法: std::string tag = sprite.get_tag(); //返回角色的标签
set_tag方法返回对角色的引用。
58. get_screen / getscreen
作用: 获取角色所绑定的 Screen 对象。
用法: Screen* s = sprite.getscreen();
提示: 也可以直接使用全局的屏幕指针来使用屏幕对象,即g_screen。
用法: g_screen->bgcolor(“black”);
代理 Screen 方法（快捷调用）
以下方法实际上是调用其绑定的 Screen 对象的同名方法，提供便捷访问：
done() → screen.mainloop() → 进入事件循环
bgpic(path) → 设置背景图
title(s) → 设置窗口标题
setup(w, h) → 设置窗口大小
bgcolor(…) → 设置背景色
delay(ms) → 全局延迟
tracer(bool) → 设置是否自动刷新
wait(seconds) → 等待
update() → 手动刷新屏幕
clear() → 全部擦除
这些方法让角色可以直接控制屏幕，无需持有 Screen 指针。
曲线绘图（高级）
59. bezierQuad(start, end, control,steps=12)
作用: 绘制二次贝塞尔曲线。
用法: sprite.bezierQuad({0,0}, {100,100}, {50,200});
返回对角色的引用。
60. bezier / bezierCubic(start, end, ctrl1, ctrl2,steps=20)
作用: 绘制三次贝塞尔曲线。
用法: sprite.bezier({0,0}, {100,100}, {30,200}, {70,-50});
返回对角色的引用。
61. bspline(controlPoints,steps=20)
作用: controlPoints是存储Point的向量。这个方法会绘制B样条曲线（需要至少4个控制点）。
用法: sprite.bspline({{0,0}, {50,100}, {100,50}, {150,0}});
返回对角色的引用。
62. cubicspline(points,steps=10)
作用: 绘制三次样条插值曲线（平滑通过所有给定点）。
用法: sprite.cubicspline({{0,0}, {50,80}, {100,20}, {150,100}});
返回对角色的引用。
63. 动态属性
作用: 给角色随时设立一个属性。角色有公共的property映射（类似Python字典）。通过建立从字符串到字符串或者其它数据类型的映射来完成角色的动态属性设立。
举例：
#include “sprites.h” //包含C++精灵库
#include <string>
using namespace std;
Screen sc;
Sprite *bug = new Sprite(“res/bug.png”);//new Sprite命令建立角色返回的地址给bug指针
int main(){ //命令行参数接收表,也可以不写
bug->property[“life”] = 10; //设生命有10条
while(true){
bug->property[“life”]–;
//to_string为把整数转换成字符串
sc.title(to_string(static_cast<int>(bug->property[“life”]))); //要用static_cast<int>强制转换
if(!bug->property[“life”]){ bug->kill();break;} //只有用new命令建立的角色才能用kill!
sc.wait(0.01);
}
sc.done();
return 0;
}
64. txt2png命令
作用：这是一个有趣的命令，角色的txt2png命令能把文字转换成图像，生成的文字颜色采用角色的画笔颜色。
它会返回一个pair<int,int>,存储图像的宽度和高度，以下都是把”C++精灵库”转换成图片，共有三种用法：
0 表示颜色的色相，这里就是红色，也可用RGB等形式。
sprite.color(0);
std::string s=”C++精灵库”;
一. 默认字体风格,
自动生成输出文件名，生成的文件名是filePath=”res/” + s + “_.png”;
语法: sprite.txt2png(s); //把s字符串转换成png，存储在filePath。
二. 默认字体风格,但指定文件名
语法: sprite.txt2png(s,”res/pxC++编辑器.png”);
三. 指定字体风格,指定文件名
语法: sprite.txt2png(s,{“楷体”,”32″,”italic”}, “res/pxC++编辑器.png”);
生成了图片后，可以把这些图片再次加载进来，形成新的角色。
65. set_flag命令
作用: 设置角色的标志
语法: sprite.set_flag(“dead”); //标记sprite已经死了
66. get_flag命令
作用: 获取角色的标志
语法: sprite.get_flag();
67. begin_poly命令
作用: 开始画多边形并记录顶点
语法: sprite.begin_poly()
返回对角色的引用。
68. end_poly命令
作用: 结束画多边形
语法: sprite.end_poly()
返回对角色的引用。
69. get_poly命令
作用: 得到所画的多边形的顶点
语法: std::vector<std::pair<float,float> > vers= sprite.get_poly();
