first commit

src/NetHack_3.7/src/nhlua.c

@@ -1,7 +1,43 @@
 /* NetHack 3.7	nhlua.c	$NHDT-Date: 1695159626 2023/09/19 21:40:26 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.115 $ */
 /*      Copyright (c) 2018 by Pasi Kallinen */
 /* NetHack may be freely redistributed.  See license for details. */
-
+/*
+nhl_get_cmd_key：此函数用于从命令名获取对应的键值，接受一个字符串参数作为命令名，返回对应的键值。
+nhl_callback：此函数用于添加或删除一个Lua函数回调。它接受两个或三个参数，分别是事件名、函数名和一个可选的布尔值。如果布尔值为真，将删除回调；否则，将添加回调。
+nhl_doturn：此函数用于处理游戏的每一回合。
+nhl_debug_flags：此函数用于获取或设置调试标志。
+nhl_timer_has_at：此函数用于检查指定时间是否有计时器事件。
+nhl_timer_peek_at：此函数用于查看指定时间的计时器事件。
+nhl_timer_stop_at：此函数用于停止指定时间的计时器事件。
+nhl_timer_start_at：此函数用于启动指定时间的计时器事件。
+nhl_gamestate：此函数用于获取游戏状态。
+nhl_test：此函数用于进行测试。
+nhl_getmap：此函数用于获取地图信息。
+splev_typ2chr：此函数用于将地图类型转换为字符表示。
+nhl_gettrap：此函数用于获取陷阱信息。
+nhl_deltrap：此函数用于删除陷阱。
+nhl_impossible：此函数用于处理不可能发生的情况，通常用于调试。
+nhl_pline：此函数用于在游戏中输出一条消息。
+nhl_verbalize：此函数用于让角色说出一句话。
+nhl_parse_config：此函数用于解析配置文件。
+nhl_menu：此函数用于创建一个菜单。
+nhl_text：此函数用于处理文本信息。
+nhl_getlin：此函数用于获取用户输入的一行文本。
+nhl_makeplural：此函数用于将单词转换为复数形式。
+nhl_makesingular：此函数用于将单词转换为单数形式。
+nhl_s_suffix：此函数用于添加名词所有格后缀。
+nhl_ing_suffix：此函数用于添加动词进行时后缀。
+nhl_an：此函数用于在单词前添加不定冠词（a/an）。
+nhl_rn2：此函数用于生成一个随机数。
+nhl_random：此函数用于生成一个随机数。
+nhl_level_difficulty：此函数用于获取当前关卡的难度。
+init_nhc_data：此函数用于初始化游戏数据。
+nhl_push_anything：此函数用于将任意类型的数据压入Lua栈。
+nhl_meta_u_index：此函数用于处理用户数据的索引。
+nhl_meta_u_newindex：此函数用于处理用户数据的新索引。
+nhl_u_clear_inventory：此函数用于清空用户的物品栏
+nhl_u_giveobj：此函数用于给用户添加一个物品。
+init_u_data：此函数用于初始化用户数据。*/
 #include "hack.h"
 #include "dlb.h"
 

src/NetHack_3.7/src/o_init.c

@@ -2,6 +2,29 @@
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /*-Copyright (c) Robert Patrick Rankin, 2011. */
 /* NetHack may be freely redistributed.  See license for details. */
+/*putstr(tmpwin, iflags.menu_headings, let_to_name(oclass, FALSE, FALSE)); - 这个函数可能用于在一个临时窗口（tmpwin）中输出一个字符串。在这里，它用于显示一个新类别的标题。
+
+Strcpy(buf, objects[dis].oc_pre_discovered ? "* " : " "); - Strcpy 是用来复制字符串的函数。在这里，它将一个字符串（带有星号的前缀或空格）复制到缓冲区（buf）中。
+
+(void) sortloot_descr(dis, &buf[2]); - 这个函数可能用于根据某种排序规则对战利品（loot）进行描述。它会修改缓冲区（buf）中的内容。
+
+disco_append_typename(buf, dis); - 这个函数可能用于将对象类型名称附加到缓冲区（buf）中。
+
+y_n("Dump information about all artifacts?") - 这个函数可能用于询问用户是否要显示关于所有文物的信息。
+
+dump_artifact_info(tmpwin); - 这个函数可能用于将所有文物的信息输出到临时窗口（tmpwin）中。
+
+disp_artifact_discoveries(tmpwin); - 这个函数可能用于显示已发现的文物信息，并将其输出到临时窗口（tmpwin）中。
+
+def_char_to_objclass(c); - 这个函数可能用于将一个字符转换为一个对象类别。
+
+oclass_to_name(oclass, buf); - 这个函数可能用于将对象类别转换为一个名称，并将其存储在缓冲区（buf）中。
+
+qsort(sorted_lines, sorted_ct, sizeof (char *), discovered_cmp); - qsort 是一个用于对数据进行快速排序的函数。在这里，它用于对已发现的项目进行排序。
+
+dupstr(buf); - 这个函数可能用于复制一个字符串。
+
+discovered_cmp(a, b); - 这个函数可能用于比较两个已发现的项目，以便在排序时使用。*/
 
 #include "hack.h"
 

src/NetHack_3.7/src/objects.c

@@ -1,6 +1,18 @@
 /* NetHack 3.7	objects.c	$NHDT-Date: 1596498192 2020/08/03 23:43:12 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.66 $ */
 /* Copyright (c) Mike Threepoint, 1989.                           */
 /* NetHack may be freely redistributed.  See license for details. */
+/*#include "config.h" #include "obj.h"
+#include "prop.h" #include "skills.h" #include "color.h" #include "objclass.h"
+// 存储对象描述的初始数组 NEARDATA struct objdescr obj_descr_init[NUM_OBJECTS + 1] = { #define OBJECTS_DESCR_INIT #include "objects.h" #undef OBJECTS_DESCR_INIT };
+// 存储对象类别的初始数组 NEARDATA struct objclass obj_init[NUM_OBJECTS + 1] = { #define OBJECTS_INIT #include "objects.h" #undef OBJECTS_INIT };
+void objects_globals_init(void); /* 在hack.h中定义，但我们使用的是config.h */
+// 全局对象描述和对象类别的初始化函数 struct objdescr obj_descr[SIZE(obj_descr_init)]; struct objclass objects[SIZE(obj_init)];
+/*void objects_globals_init(void) { // 将初始值复制到全局数组中 memcpy(obj_descr, obj_descr_init, sizeof(obj_descr)); memcpy(objects, obj_init, sizeof(objects)); }
+这是NetHack游戏的objects.c文件。
+它包含了对象描述和类别的定义和初始化。
+obj_descr_init和obj_init数组用于存储对象描述和类别的初始值。
+objects_globals_init函数用于将全局数组obj_descr和objects初始化为初始值。
+这些数组在整个游戏中用于存储关于对象的信息。 */
 
 #include "config.h"
 #include "obj.h"

src/NetHack_3.7/src/objnam.c

@@ -2,6 +2,17 @@
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /*-Copyright (c) Robert Patrick Rankin, 2011. */
 /* NetHack may be freely redistributed.  See license for details. */
+/*结构体 Jitem: 这个结构体包含了一个整数 item 和一个指向字符串的指针 name。它可能用于存储关于游戏物品的信息。
+宏定义 BSTRCMPI, BSTRNCMPI, Strcasecpy, GemStone: 这些宏定义用于简化代码中的字符串比较和复制操作，以及判断某种类型的物品是否为宝石或石头。
+结构体 _readobjnam_data: 这个结构体包含了一系列整数和布尔类型的变量，用于存储物品的各种属性，如腐蚀程度、锁定状态、真实性、破损程度等。还包括一些字符串缓冲区，可能用于存储物品的名称或特殊描述。
+函数 strprepend: 这个函数可能用于将一个字符串添加到另一个字符串的开头。
+函数 nextobuf: 这个函数可能用于在缓冲区中获取下一个可用的字符串。
+函数releaseobuf: 这个函数可能用于释放之前分配的字符串缓冲区。
+函数 xcalled, xname_flags, minimal_xname: 这些函数可能用于生成和处理物品名称及其属性。
+函数 add_erosion_words: 这个函数可能用于将物品的腐蚀程度描述添加到物品名称中。
+函数 doname_base: 这个函数可能用于生成基本的物品名称，包括其属性和特殊描述。
+
+*/
 
 #include "hack.h"
 

src/NetHack_3.7/src/options.c

@@ -2,6 +2,23 @@
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /*-Copyright (c) Michael Allison, 2008. */
 /* NetHack may be freely redistributed.  See license for details. */
+/*bad_negation(const char *, boolean)：处理选项取反的错误情况。
+change_inv_order(char *)：更改物品显示顺序。
+warning_opts(char *, const char *)：处理关于警告的选项。
+feature_alert_opts(char *, const char *)：处理特性警报选项。
+duplicate_opt_detection(int)：检测选项重复。
+complain_about_duplicate(int)：对重复的选项进行投诉。
+length_without_val(const char *, int len)：计算选项名长度，不包括选项值。
+determine_ambiguities(void)：确定选项名称中的歧义。
+check_misc_menu_command(char *, char *)：检查杂项菜单命令。
+opt2roleopt(int)：将选项转换为角色选项。
+getoptstr(int, int)：获取选项字符串。
+saveoptstr(int, const char *)：保存选项字符串。
+unsaveoptstr(int, int)：取消保存选项字符串。
+shared_menu_optfn(int, int, boolean, char *, char *)：处理共享菜单选项功能。
+spcfn_misc_menu_cmd(int, int, boolean, char *, char *)：特殊功能杂项菜单命令。
+attr2attrname(int)：将属性值转换为属性名称。
+basic_menu_colors(boolean)：设置基本菜单颜色。*/
 
 #ifdef OPTION_LISTS_ONLY /* (AMIGA) external program for opt lists */
 #include "config.h"

src/NetHack_3.7/src/pager.c

@@ -5,6 +5,29 @@
 
 /* This file contains the command routines dowhatis() and dohelp() and */
 /* a few other help related facilities */
+/*1. dohelp()：这个函数是NetHack游戏中的帮助命令，用于显示游戏的帮助信息。
+
+2. is_swallow_sym()：这个函数用于判断一个符号是否表示被吞噬的状态。
+
+3. append_str()：这个函数用于将一个字符串追加到另一个字符串的末尾。
+
+4. trap_description()：这个函数用于生成陷阱的描述信息。
+
+5. look_at_object()：这个函数用于查看游戏中的物品，并生成物品的描述信息。
+
+6. look_at_monster()：这个函数用于查看游戏中的怪物，并生成怪物的描述信息。
+
+7. sysopt.fmtd_wizard_list：这个选项用于格式化向导模式命令列表。
+
+8. putstr()：这个函数用于将一个字符串输出到指定的窗口。
+
+9. display_nhwindow()：这个函数用于显示一个NetHack窗口。
+
+10. destroy_nhwindow()：这个函数用于销毁一个NetHack窗口。
+
+11. dispfile_help()：这个函数用于显示帮助文件。
+
+12. dispfile_shelp()：这个函数用于显示简短的帮助文件。*/
 
 #include "hack.h"
 #include "dlb.h"

src/NetHack_3.7/src/pickup.c

@@ -6,6 +6,21 @@
 /*
  *      Contains code for picking objects up, and container use.
  */
+ /*1. in_container(struct obj *)：这个函数用于将指定的物品放入容器中。
+2. out_container(struct obj *)：这个函数用于将指定的物品从容器中取出。
+3. mbag_item_gone(boolean, struct obj *, boolean)：这个函数用于处理从魔法袋中移除物品的情况，包括物品消失和重量变化。
+4. stash_ok(struct obj *)：这个函数用于判断一个物品是否可以被存放在容器中。
+5. explain_container_prompt(boolean)：这个函数用于显示容器操作的提示信息，如放入、取出物品等。
+6. traditional_loot(boolean)：这个函数用于实现传统的物品搜刮操作，如打开容器、拾取物品等。
+7. menu_loot(int, boolean)：这个函数用于显示一个菜单，让玩家选择从容器中拾取或放入物品。
+8. tip_ok(struct obj *)：这个函数用于判断一个容器是否可以被倾倒。
+9. tipcontainer_gettarget(struct obj *, boolean *)：这个函数用于获取玩家选择的倾倒容器的目标。
+10. tipcontainer_checks(struct obj *, struct obj *, boolean)：这个函数用于检查倾倒容器操作是否合法，如容器是否已满等。
+11. in_or_out_menu(const char *, struct obj *, boolean, boolean, boolean, boolean)：这个函数用于显示一个菜单，让玩家选择将物品放入容器或从容器中取出。
+12. able_to_loot(coordxy, coordxy, boolean)：这个函数用于判断玩家是否能够在指定位置搜刮物品。
+13. reverse_loot(void)：这个函数用于判断玩家是否希望反向搜刮，即从容器中取出物品。
+14. mon_beside(coordxy, coordxy)：这个函数用于判断指定位置是否有怪物。
+15. do_loot_cont(struct obj **, int, int)：这个函数用于处理玩家搜刮容器中的物品。*/
 
 #include "hack.h"
 

src/NetHack_3.7/src/pline.c

@@ -2,6 +2,12 @@
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /*-Copyright (c) Robert Patrick Rankin, 2018. */
 /* NetHack may be freely redistributed.  See license for details. */
+/*putmesg(const char *)：这个函数用于将传入的字符串（游戏中的消息）输出到屏幕上。
+You_buf(int)：这个函数用于生成一个包含 "你"（You）的字符串，用于游戏中的消息。例如，当你在游戏中拾起一把剑时，消息可能是 "你拾起了一把剑"。
+execplinehandler(const char *)：这个函数是在定义了 MSGHANDLER 时使用的。它用于执行一个外部程序来处理游戏中的消息。这个函数会检查环境变量 "NETHACK_MSGHANDLER"，如果存在，则使用该程序处理消息。
+maybe_play_sound(const char *)：这个函数用于在游戏中播放声音。它会检查传入的字符串是否与配置文件中定义的声音关联，如果是，则播放相应的声音。
+impossible(const char *, ...)：这个函数用于处理游戏中的异常情况。当发生不可能的事件时，它会输出一条消息给玩家，并提示玩家报告这个问题。在某些情况下，它还会提示玩家保存游戏并重新加载，以解决问题。
+*/
 
 #include "hack.h"
 

src/NetHack_3.7/src/polyself.c

@@ -18,7 +18,12 @@
  *
  *    polymon (called directly)             usually golem petrification
  */
-
+/*see_monsters()：此函数用于更新玩家视野内的怪物信息，以便玩家可以看到附近的怪物。
+encumber_msg()：此函数用于检查玩家的负重情况，如果负重过重，会给出相应的提示信息。
+retouch_equipment(2)：此函数用于重新调整玩家的装备，例如在玩家变形时调整装备以适应新的形态。
+selftouch()：此函数用于处理玩家自身触摸的情况，例如玩家触摸到具有石化效果的物体，可能导致玩家石化。
+hides_under()：此函数用于检查玩家是否可以在当前位置下隐藏，例如在地上的物品堆下隐藏。
+canletgo()：此函数用于检查玩家是否可以放下或释放手中的物品，例如在需要脱下手套时放下武器。*/
 #include "hack.h"
 
 static void check_strangling(boolean);