From 5d3205e1e9e29bc477e7f785a263cd43dd9cd1bd Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Sat, 15 Apr 2023 06:29:59 -0400 Subject: [PATCH] Add explanatory comments. --- NEWS.adoc | 2 +- advent.h | 32 +++++++++++++++++++++++++++----- main.c | 4 ++++ misc.c | 4 +++- 4 files changed, 35 insertions(+), 7 deletions(-) diff --git a/NEWS.adoc b/NEWS.adoc index b879e17..c390e7e 100644 --- a/NEWS.adoc +++ b/NEWS.adoc @@ -2,7 +2,7 @@ // SPDX-FileCopyrightText: Eric S. Raymond // SPDX-License-Identifier: CC-BY-4.0 -Reoisitory head:: +Repository head:: Savefiles now have an identifying magic cookie at the front. Resume detects if a save has incompatible endianness. diff --git a/advent.h b/advent.h index cb2b71b..0cbe7fb 100644 --- a/advent.h +++ b/advent.h @@ -48,12 +48,27 @@ #define IS_FIXED -1 #define IS_FREE 0 -/* PROP_STASHED maps a state property value to a negative range, where the object - * cannot be picked up but the value can be recovered later. */ #ifndef FOUNDBOOL -/* PROP_STASHED needs ro avoid colliding with -1, - * which has its own meaning as STATE_NOTFOUND. */ -#define PROP_STASHED(obj) (STATE_NOTFOUND - game.objects[obj].prop) +/* (ESR) It is fitting that translation of the original ADVENT should + * have left us a maze of twisty little conditionals that resists all + * understanding. Setting and use of what is now the per-object state + * member (which used to be an array of its own) is our mystery. This + * state tangles together information about whether the object is a + * treasure, whether the player has seen it yet, and its activation + * state. + * + * Things we think we know: + * + * STATE_NOTFOUND is only set on treasures. Non-treasures start the + * game in STATE_FOUND. + * + * PROP_STASHED is supposed to map a state property value to a + * negative range, where the object cannot be picked up but the value + * can be recovered later. Various objects get this peoperty when + * the cave starts to close. On;y seems to be signifucant for the bird + * and readable objects, notably the clam/oyster - but the code around + * those test is difficult to read. */ +#define PROP_STASHED(obj) (-1 - game.objects[obj].prop) #define PROP_IS_STASHED(obj) (game.objects[obj].prop < STATE_NOTFOUND) #define PROP_IS_NOTFOUND(obj) (game.objects[obj].prop == STATE_NOTFOUND) #define PROP_IS_FOUND(obj) (game.objects[obj].prop == STATE_FOUND) @@ -63,6 +78,13 @@ #define PROP_IS_NOTFOUND2(g, o) (g.objects[o].prop == STATE_NOTFOUND) #define PROP_IS_INVALID(val) (val < -MAX_STATE - 1 || val > MAX_STATE) #else +/* (ESR) Only the boldest of adventurers will explore here. This + * alternate set of definitions for the macros above was an attempt to + * break from out of the state encoding a per-object "found" member + * telling whether or not the player has seen the object. These is one + * accompanying change in misc.c. What's broken when you try to use + * thus is PROP_IS_STASHED_OR_UNSEEN. + */ #define PROP_STASHED(obj) (-game.objects[obj].prop) #define PROP_IS_STASHED(obj) (game.objects[obj].prop < 0) #define PROP_IS_NOTFOUND(obj) (!game.objects[obj].found) diff --git a/main.c b/main.c index 92ab1b1..c688018 100644 --- a/main.c +++ b/main.c @@ -917,6 +917,10 @@ static void listobjects(void) obj = obj - NOBJECTS; if (obj == STEPS && TOTING(NUGGET)) continue; + /* (ESR) Warning: it looks like you could get away with + * running this code only on objects with the treasure + * property set. Nope. There is mystery here. + */ if (PROP_IS_STASHED_OR_UNSEEN(obj)) { if (game.closed) continue; diff --git a/misc.c b/misc.c index 0d540c6..f6a37f7 100644 --- a/misc.c +++ b/misc.c @@ -600,8 +600,10 @@ void put(obj_t object, loc_t where, int pval) * negated game.prop values for the repository objects. */ { move(object, where); + /* (ESR) Read this in combination with the macro defintions in advebt.h. + */ #ifndef FOUNDBOOL - game.objects[object].prop = (-1) - pval;; // Needs to stay synchronized with PROP_STASHED + game.objects[object].prop = (-1) - pval; // Needs to stay synchronized with PROP_STASHED #else game.objects[object].prop = - pval;; // Needs to stay synchronized with PROP_STASHED game.objects[object].found = true; -- 2.31.1