Hello, loves!

I was watching Antiques Roadshow, as one does, when it came to me that a tiny object might be just the thing for DungeonView. Let’s find out.

DungeonView needs a lot of work, but the code of concern this morning is this:

class DungeonView(arcade.View):
    def __init__(self, dungeon, testing=False):
        ...
        self.dungeon_floor_sprites = arcade.SpriteList()
        self.cell_sprites: dict[Cell, Sprite] = dict()
        self.content_views: dict[Content, ContentView] = dict()
        self.content_views_by_cell: dict[Cell, list[ContentView]] = defaultdict(list)
        self.illuminated_cells: set[Cell] = set()
        self.content_sprite_list = None
        ...

DungeonView has way too many collections, but this morning we’ll look at these two:

        self.dungeon_floor_sprites = arcade.SpriteList()
        self.cell_sprites: dict[Cell, Sprite] = dict()

Those are used, variously:

    def setup(self):
        self.setup_scroller()
        self.setup_cameras()
        self.dungeon_floor_sprites = arcade.SpriteList()
        self.create_rooms(self.dungeon_floor_sprites)
        self.create_content_lists()
    def create_rooms(self, shape_list):
        for room in self.dungeon.rooms:
            view = RoomView(room)
            for cell, sprite in view.generate_sprites(self.dungeon.layout):
                self.cell_sprites[cell] = sprite
                self.dungeon_floor_sprites.append(sprite)
    def on_draw(self):
        self.clear()
        self.scroll_dungeon_camera()
        with self.dungeon_camera.activate():
            self.dungeon_floor_sprites.draw()
            self.draw_contents()
            self.draw_passages()
            self.draw_flood()
        with self.scroller_camera.activate():
            self.scroller.draw()
    def illuminate_cell(self, cell):
        sprite = self.cell_sprites[cell]
        sprite.visible = True
        self.illuminated_cells.add(cell)
        for content_view in self.content_views_by_cell[cell]:
            content_view.just_illuminate()

What’s going on is simpler than this may appear. For drawing efficiency, we keep all the floor cell tile sprites in a SpriteList, which can be drawn all in one go. But when we illuminate a room, we need to set visible on the individual sprites for illuminated cells, so we need access to the sprite for each particular cell.

So, currently, we have the full list dungeon_floor_sprites and a dictionary, cell_sprites, for those two purposes.

The idea this morning is to cover both uses with a single object. Let’s TDD it, just for fun.

class TestKeyedSpriteList:
    def test_creation(self):
        assert False

Fails. Perfect. I think we’ll write very few tests here, but let’s start out in the classic form, just creating the object.

class TestKeyedSpriteList:
    def test_creation(self):
        keyed = KeyedSpriteList(SpriteList())

Fails because there is no such thing. Make such thing:

class KeyedSpriteList:
    def __init__(self, sprite_list):
        self.sprite_list = sprite_list

I didn’t declare the sprite_list type, because for testing purposes, I want to use an ordinary list. That’s also part of why we provide the sprite list to our new object. Another reason is that we might conceivably want to create the actual SpriteList externally, although I think that will be unlikely.

New test:

    def test_add_and_access(self):
        contents = list()
        keyed = KeyedSpriteList(contents)
        keyed.add('cell_a', 'sprite_A')
        keyed.add('cell_b', 'sprite_B')
        assert len(contents) == 2
        assert 'sprite_A' in contents
        assert 'sprite_B' in contents
        assert keyed['cell_a'] == 'sprite_A'
        assert keyed['cell_b'] == 'sprite_B'

We expect to add a cell and a sprite, but the object doesn’t care what we add. We expect all the sprites to show up in our provided content list and we expect to be able to access them by name using a subscripting notation.

Test fails, of course. We code:

class KeyedSpriteList:
    def __init__(self, sprite_list):
        self.sprite_dict = dict()
        self.sprite_list = sprite_list
    def add(self, cell, sprite):
        self.sprite_dict[cell] = sprite
        self.sprite_list.append(sprite)

Test still fails but I expect it to fail on the second last assert.

>       assert keyed['cell_a'] == 'sprite_A'
               ^^^^^^^^^^^^^^^
E       TypeError: 'KeyedSpriteList' object is not subscriptable

That’s just right. Make it work:

class KeyedSpritList:
    def __getitem__(self, cell):
        return self.sprite_dict[cell]

And we are green.

And we are at a nice point to commit this code. Commit: TDDing KeyedSpriteList.

Now let’s move the KeyedSpriteList to the ‘src’ tree: I built it inside the test file, as I often do with h/t to Keith Braithwaite. Done. Commit: move KSL to prod.

Brief Reflection

We could just bang this thing in: there are only a few places needing to be changed, including, I think, one test that may break along the way.

But let’s pretend that we have lots of places needing to be changed, and do it incrementally, one place at a time, never breaking anything (well, trying never to break anything), rinse repeat.

First, we create the new object in DungeonView’s init.

class DungeonView:
    def __init__...
        ...
        self.dungeon_floor_sprites = arcade.SpriteList()
        self.keyed_floor_sprites = KeyedSpriteList(self.dungeon_floor_sprites)
        self.cell_sprites: dict[Cell, Sprite] = dict()
        ...

No harm done. Commit: converting to use KSL over weeks and weeks.

Now we have to get it loaded.

I tried this:

    def create_rooms(self, shape_list):
        for room in self.dungeon.rooms:
            view = RoomView(room)
            for cell, sprite in view.generate_sprites(self.dungeon.layout):
                self.cell_sprites[cell] = sprite
                self.dungeon_floor_sprites.append(sprite)
                self.keyed_floor_sprites.add(cell, sprite)

But tests fail because we are adding to the same SpriteList twice. We need to give our KSL its own list.

        self.keyed_floor_sprites = KeyedSpriteList(arcade.SpriteList())

Tests go green. Code above is OK. Commit: converting to use KSL over weeks and weeks.

Weeks later, find a place that can use the new object: draw.

class DungeonView:
    def on_draw(self):
        self.clear()
        self.scroll_dungeon_camera()
        with self.dungeon_camera.activate():
            self.dungeon_floor_sprites.draw()
            self.draw_contents()
            self.draw_passages()
            self.draw_flood()
        with self.scroller_camera.activate():
            self.scroller.draw()

We could fetch the list and draw it but why not let the KSL do the job. Add the method and use it.

class KeyedSpriteList:
    def draw(self):
        self.sprite_list.draw()
class DungeonView:
    def on_draw(self):
        self.clear()
        self.scroll_dungeon_camera()
        with self.dungeon_camera.activate():
            self.keyed_floor_sprites.draw()
            self.draw_contents()
            self.draw_passages()
            self.draw_flood()
        with self.scroller_camera.activate():
            self.scroller.draw()

We do test that one on the screen, and are not surprised when it works. Commit. Is the floor list used anywhere else? It appears not. Remove all the references.

    def create_rooms(self):
        for room in self.dungeon.rooms:
            view = RoomView(room)
            for cell, sprite in view.generate_sprites(self.dungeon.layout):
                self.cell_sprites[cell] = sprite
                self.keyed_floor_sprites.add(cell, sprite)

We discovered along the way that create_rooms wasn’t even using the provided list, so we removed the parameter. Commit.

Users of cell_sprites are of interest now. Here’s one:

    def illuminate_cell(self, cell):
        sprite = self.cell_sprites[cell]
        sprite.visible = True
        self.illuminated_cells.add(cell)
        for content_view in self.content_views_by_cell[cell]:
            content_view.just_illuminate()

We can use KSL here.

    def illuminate_cell(self, cell):
        sprite = self.keyed_floor_sprites[cell]
        sprite.visible = True
        self.illuminated_cells.add(cell)
        for content_view in self.content_views_by_cell[cell]:
            content_view.just_illuminate()

Commit. That’s the only local reference that was left. A test will fail when we remove the instance variable. It’s referring to cell_sprites and we make it refer to keyed_floor_sprites and we’re good.

Six commits, basically one possible change at a time, no breakage. And we have reduced two instance variables down to one, and removed a few lines of code. Modified a few more.

Reflection

Was it worth all that to remove what amounts to a single instance variable? I don’t know. It has taken an hour to do the work and write the article. We have taken two objects which could in principle get out of sync and encapsulated them so that they will always stay in sync. We have taken two lines of code that always had to be done together and put them together in one place that everyone else just uses without knowing what’s behind the curtain.

A better question to ask might be “Do you kind of wish you had thought of this object at the moment you created that second structure, whichever one it was?” And that one is easy: I do wish I had, and I’m a bit more dedicated to noticing places where a tiny object can help me.

Part of my purpose in programming, whether for show, like here, or for real, as I used to do in the olden days, is to keep my design as clear and proper as I can. I do not have the ability to figure that out in advance, and if anyone has, I have not met them. I do have the ability to improve things as I become aware of them, and every decent programmer has that ability as well.

Summary

A tiny object makes the code a bit better. It was easy to write, easy to install, and is cute as a kitten. Well, almost.

See you next time!

Hello, loves!

I’ve decided to commit this and refactor. Can always reset if I have to. General rule: try always to move forward.

We’ll begin with some tests for what we have. What do we have? I don’t know, that was hours ago. Here’s just the DungeonView init, evidence that all is not well:

class DungeonView(arcade.View):
    def __init__(self, dungeon, testing=False):
        if not testing:
            super().__init__()
        self.dungeon = dungeon
        self.pub_sub = dungeon.pub_sub
        self.subscribe(dungeon, self.pub_sub)
        self.setup_assets()
        self.key_lock = None
        self.room_sprite_list = None
        self.content_views: dict[Content, ContentView] = dict()
        self.content_views_by_room: dict[Room, list[ContentView]] = dict()
        self.content_views_by_cell: dict[Cell, list[ContentView]] = defaultdict(list)
        self.room_views: dict[Room, RoomView] = dict()
        self.cell_sprites: dict[Cell, Sprite] = dict()
        self.illuminated_cells: set[Cell] = set()
        self.content_sprite_list = None
        self.dungeon_camera = None
        self.dungeon_camera_bounds = None
        self.scroller = None
        self.scroller_camera = None

We can be pretty sure that 17 lines of instance variables is about 13 too many. So we’ll keep that in mind. Are there any of those that are no longer referenced? content_views_by_room seems not to be. Removed, commit.

What about the room_views? They’re defined but not used. Remove, commit.

These two structures seem to have some redundancy:

    def __init...
        self.room_sprite_list = arcade.SpriteList()
        self.content_views: dict[Content, ContentView] = dict()
    def setup(self):
        self.setup_scroller()
        self.setup_cameras()
        self.room_sprite_list = arcade.SpriteList()
        self.create_rooms(self.room_sprite_list)
        self.create_content_lists()
    def create_rooms(self, shape_list):
        for room in self.dungeon.rooms:
            view = RoomView(room)
            for cell, sprite in view.generate_sprites(self.dungeon.layout):
                self.cell_sprites[cell] = sprite
                self.room_sprite_list.append(sprite)
    def on_draw(self):
        self.clear()
        self.scroll_dungeon_camera()
        with self.dungeon_camera.activate():
            self.room_sprite_list.draw()
            self.draw_contents()
            self.draw_passages()
            self.draw_flood()
        with self.scroller_camera.activate():
            self.scroller.draw()

Can’t we just put them in cell_sprites and draw the values? No the one is a SpriteList, which we really want to use. Let’s rename the member to dungeon_floor_sprites. Commit.

I think that’s all the redundancy I can eliminate from here. But I think there are some unused bits elsewhere.

The only caller of RoomView.illuminate is a test:

    def test_room_view_illuminate(self):
        layout = DungeonLayout(20,20)
        dungeon = Dungeon(layout)
        dungeon_view = DungeonView(dungeon, True)
        cells = [Cell(x,y) for x in range(9,15) for y in range(9,15)]
        room = Room(cells, layout)
        layout.add_room(room)
        room_view = RoomView(room)
        room_view.cell_sprites = {cell: FakeSprite() for cell in cells}
        room_view.illuminate(dungeon_view, Cell(12, 12), 3)
        lit_cell = Cell(13, 13)
        lit = room_view.cell_sprites[lit_cell]
        assert lit_cell in dungeon_view.illuminated_cells
        assert lit.visible == True
        unlit_cell = Cell(9, 9)
        assert not unlit_cell in dungeon_view.illuminated_cells
        unlit = room_view.cell_sprites[unlit_cell]
        assert unlit.visible == False

Ugly. I think we’ll remove RoomView.illuminate and let this test be our lead-in to actual testing. Sure enough, the test fails.

The good news is, I have a test that is working and checking the new code:

    def test_room_view_illuminate(self):
        layout = DungeonLayout(20,20)
        dungeon = Dungeon(layout)
        dungeon_view = DungeonView(dungeon, True)
        cells = [Cell(x,y) for x in range(9,15) for y in range(9,15)]
        room = Room(cells, layout)
        layout.add_room(room)
        layout.ensure_connected()
        layout.make_passages()
        layout.make_borders()
        dungeon.just_set_player_position(Cell(12,12))
        dungeon_view.create_rooms(arcade.SpriteList())
        dungeon_view.illuminate_around_dot()
        lit_cell = Cell(13, 13)
        lit = dungeon_view.cell_sprites[lit_cell]
        assert lit_cell in dungeon_view.illuminated_cells
        assert lit.visible == True
        unlit_cell = Cell(9, 9)
        assert not unlit_cell in dungeon_view.illuminated_cells
        unlit = dungeon_view.cell_sprites[unlit_cell]
        assert unlit.visible == False

The bad news is that it is capital U Ugly. But it is a place to stand, and from which to do better.

I’m calling this progress. The DungeonView is simpler and it has an actual test that is exercising most of the new hammered-in code. So we can clean up this test, refactor the code, and move toward better.

And that is the name of the game. See you next time!

Hello, loves!

OK, let’s do the thing we love: find something to improve, and improve it. Shall we start where we left off? Result: Not as joyful as some days.

We pared down the RoomView by removing its references to layout, dungeon, and dungeon view, passing them as parameters when they were needed. Pretty much what the received wisdom would suggest and I’ve done it many times and don’t recall ever regretting it. There is a place for encapsulating a bunch of objects that need to be processed together, often using the pattern called Method Object that replaces a method with a small object bound to the info needed to do one thing, but as a rule, long-standing objects that connect to lots of other objects just make things hard to change and hard to test.

One could wonder why I do it so often.

Let’s start by looking at RoomView again and thinking about what we have wrought.

class RoomView:
    def __init__(self, room):
        self.room = room
        self.sprites = []
        self.cell_sprites = dict()
        self.texture_finder = TextureFinder()
    def create_floor(self, layout, shape_list):
        for cell in self.room:
            self.choose_flooring(layout, cell, shape_list)
    def choose_flooring(self, layout, cell, shape_list):
        texture = self.choose_flooring_texture(layout, cell)
        sprite = params.make_adjusted_sprite(cell, texture)
        self.cell_sprites[cell] = sprite
        self.sprites.append(sprite)
        shape_list.append(sprite)
    def illuminate(self, dungeon_view, center_cell, distance):
        for cell, sprite in self.cell_sprites.items():
            if cell.manhattan_distance(center_cell) < distance:
                dungeon_view.illuminate(cell)
                sprite.visible = True
    def choose_flooring_texture(self, layout, cell):
        borders: BorderList = layout.get_borders(cell)
        border_type = borders.border_string()
        name = self.texture_finder.full_name(border_type)
        return arcade.load_texture(name)

As I mentioned yesterday, it’s pretty clear that there are two things going on in this object, creating the sprites for the room’s flooring, and illuminating the sprites upon demand.

Arguably there are two phases to the sprite creation, choosing the texture to be used, and creating the actual sprite.

The two choose methods should be private, and together. Do that.

    def create_floor(self, layout, shape_list):
        for cell in self.room:
            self._choose_flooring(layout, cell, shape_list)
    def _choose_flooring(self, layout, cell, shape_list):
        texture = self._choose_flooring_texture(layout, cell)
        sprite = params.make_adjusted_sprite(cell, texture)
        self.cell_sprites[cell] = sprite
        self.sprites.append(sprite)
        shape_list.append(sprite)
    def _choose_flooring_texture(self, layout, cell):
        borders: BorderList = layout.get_borders(cell)
        border_type = borders.border_string()
        name = self.texture_finder.full_name(border_type)
        return arcade.load_texture(name)
    def illuminate(self, dungeon_view, center_cell, distance):
        for cell, sprite in self.cell_sprites.items():
            if cell.manhattan_distance(center_cell) < distance:
                dungeon_view.illuminate(cell)
                sprite.visible = True

Commit.

The question in my mind is what this object really is, since it’s not really a view, and whether it should be separated into two objects, one about choosing flooring and one about illuminating the floor.

It is not a dungeon-level object, because it thinks about textures, which are view-level, not dungeon level.

Illumination, though. The DungeonView knows, for all cells, which are illuminated. Currently the dungeon does not know whether it is illuminated or not, and we have no story that tells us that it needs to know, although it is easy to think of why we’ll need it. We don’t do things because we’re going to need them, we do them when we need them.

As written, illuminate marks sprites and informs the DungeonView that a cell is illuminated. DungeonView just does this:

class DungeonView:
    def illuminate(self, cell):
        self.illuminated_cells.add(cell)

Hm, how does the RoomView get told to illuminate, one wonders.

class DungeonView:
    def illuminate_around_dot(self):
        dot = self.dungeon.player_cell
        if not dot: return # crock to allow a test to run
        room = dot.room
        radius = 1000 if self.dungeon.dot_has('a brilliant torch') else 4
        self.room_views[room].illuminate(self, dot, radius)
        for content_view in self.content_views_by_room[room]:
            content_view.illuminate(dot, radius)

While we’re at it:

class ContentView:
    def illuminate(self, dot, range):
        if dot.manhattan_distance(self.cell) < range:
            self.sprite.visible = True

Now as things stand, the DungeonView has all the sprites for the floor, all in a big sprite list. And the RoomView maintains a dictionary from cell to sprite, one such dictionary for each room.

I just noticed that RoomView maintains the sprite_list member but never uses it. Remove it. Two more lines gone from RoomView. Commit.

Design Thinking

I’m not ready to try this but just thinking …

The DungeonView has access to the Room instances. A Room is, among other responsibilities, a set of cells. If DungeonView maintained the mapping from cell to sprite then illumination of a room could be done in DungeonView and illuminate removed from the RoomView, removing that responsibility and leaving it as no more than a texture finder for flooring.

I think that will be better. Let’s do it.

I want to sketch some code that is like the code I’ll want for illuminate_around_dot as shown above. Maybe something like this:

    def illuminate_around_dotX(self):
        dot = self.dungeon.player_cell
        if not dot: return # crock to allow a test to run
        room = dot.room
        radius = 1000 if self.dungeon.dot_has('a brilliant torch') else 4
        for cell in room:
            if cell.manhattan_distance(dot.room) <= radius:
                self.illuminate_cell(cell)
    def illuminate_cell(self, cell):
        sprite = self.cell_sprites[cell]
        sprite.visible = True
        self.illuminated_cells.add(cell)
        for content_view in self.cell_content_view[cell]:
            content_view.illuminate()

For this to work, DungeonView needs two new dictionaries, cell_sprites, which needs to be a mapping from all cells to their sprites, and cell_content_view, a mapping from cell to a list of contents (or an empty list if absent).

To get the cell_sprites dictionary, we have to deal with the flooring logic in RoomView, which is presently passed a sprite list and adds to it. Where do we do that?

class DungeonView:
    def create_rooms(self, shape_list):
        for room in self.dungeon.rooms:
            view = RoomView(room)
            self.room_views[room] = view
            view.create_floor(self.dungeon.layout, shape_list)

I think that what we want here is for the view to act as a generator, producing a cell and a sprite for each cell in the room.

Can we build that internally to RoomView and use existing tests to be sure we’re right?

Seems like a small step. Let’s try it.

class RoomView:
    def create_floor(self, layout, shape_list):
        for cell in self.room:
            self._choose_flooring(layout, cell, shape_list)
    def _choose_flooring(self, layout, cell, shape_list):
        texture = self._choose_flooring_texture(layout, cell)
        sprite = params.make_adjusted_sprite(cell, texture)
        self.cell_sprites[cell] = sprite
        shape_list.append(sprite)

I refactor to this:

class RoomView:
    def create_floor(self, layout, shape_list):
        for cell, sprite in self.generate_sprites(layout):
            self.cell_sprites[cell] = sprite
            shape_list.append(sprite)
    def generate_sprites(self, layout):
        for cell in self.room:
            sprite = self.make_sprite(layout, cell)
            yield cell, sprite
    def _choose_flooring(self, layout, cell, shape_list):
        sprite = self.make_sprite(layout, cell)
        self.cell_sprites[cell] = sprite
        shape_list.append(sprite)
    def make_sprite(self, layout, cell):
        texture = self._choose_flooring_texture(layout, cell)
        sprite = params.make_adjusted_sprite(cell, texture)
        return sprite

This works. I note that no tests broke while I was typing that in, which tells me we probably need more testing around this. I did test in play and it works.

Now there is a generator that DungeonView can call. If we use that instead of create_floor, the RoomView will no longer have its local list of sprites. Let’s move that one line up:

    def generate_sprites(self, layout):
        for cell in self.room:
            sprite = self.make_sprite(layout, cell)
            self.cell_sprites[cell] = sprite
            yield cell, sprite

Now let’s see if we can use the generate to create our cell-to-sprite dictionary …

After more hackery than I am comfortable with, I have things working. We’ll need to consider this a spike and it needs doing over. I will not roll it back yet. I need to learn from it a bit more but here’s what I’ve got.

class RoomView:
    def create_floor(self, layout, shape_list):
        for cell, sprite in self.generate_sprites(layout):
            self.cell_sprites[cell] = sprite
            shape_list.append(sprite)
    def generate_sprites(self, layout):
        for cell in self.room:
            sprite = self.make_sprite(layout, cell)
            self.cell_sprites[cell] = sprite
            yield cell, sprite
    def make_sprite(self, layout, cell):
        texture = self._choose_flooring_texture(layout, cell)
        sprite = params.make_adjusted_sprite(cell, texture)
        return sprite

I extracted the new method make_sprite and use it in the new generate_sprites method, which keeps create_floor working, although now that the rest is working I think it’s no longer called or needed.

In DungeonView there’s more:

class DungeonView:
    def __init__(self, dungeon, testing=False):
        ...
        self.content_views_by_cell: dict[Cell, list[ContentView]] = defaultdict(list)
        self.cell_sprites: dict[Cell, Sprite] = dict()
        ...
    def make_view_and_sprite(self, cell, item):
        resources = item.resources
        scale = item.scale
        view = ContentView(cell, item, resources, scale)
        view.sprite.position = cell.center_position(cell_size)
        self.content_views[item] = view
        self.content_views_by_room[cell.room].append(view)
        self.content_views_by_cell[cell].append(view)
        self.content_sprite_list.append(view.sprite)
        if cell in self.illuminated_cells:
            view.sprite.visible = True
    def create_rooms(self, shape_list):
        for room in self.dungeon.rooms:
            view = RoomView(room)
            self.room_views[room] = view
            for cell, sprite in view.generate_sprites(self.dungeon.layout):
                self.cell_sprites[cell] = sprite
                self.room_sprite_list.append(sprite)
    def illuminate_around_dot(self):
        dot = self.dungeon.player_cell
        if not dot: return # crock to allow a test to run
        room = dot.room
        radius = 1000 if self.dungeon.dot_has('a brilliant torch') else 4
        for cell in room:
            if cell.manhattan_distance(dot) <= radius:
                self.illuminate_cell(cell)
    def illuminate_cell(self, cell):
        sprite = self.cell_sprites[cell]
        sprite.visible = True
        self.illuminated_cells.add(cell)
        for content_view in self.content_views_by_cell[cell]:
            content_view.just_illuminate()

Reflection

The bad news is that having just written about the joy I find in programming, what I’ve just done was not joyful. It was confusing, irritating, and working without a net of tests. That’s why I’m not going to commit it now, and while next time around I’ll probably just revert and do it over.

The good news is that the basic idea of generating the sprites in RoomView and handing them over to DungeonView does work. I think that the illuminate method in RoomView is no longer used.

The observations include:

• It’s just possible that despite its flaws, this is a better structure for things.
• create_rooms doesn’t create rooms and never did. Needs better name, if only create_sprites or something.
• There are way too many lists and dictionaries in DungeonView. Some of them may already be unused. Others should be obviated.
• There are no tests for any of this, and never have been.

The hopeful observation is that as I sit with it for a moment, it’s not really that bad. It might make sense not to throw it away, but instead to write the tests that we should have had right along, and then refactor this code to make it decent.

We’ll see. I’m late to my appointment with an iced Chai. See you next time!

Hello, loves!

What I love about programming. A few thoughts on what I do, and why I enjoy it so much.

Code, I guess, is the thing I’m second-best at, maybe best. I enjoy it. I’ve had similar feelings with a few other activities, sometimes writing, sometimes drawing. I link to think that I’m fairly good at all those things, if you count the people who say “I can’t draw” and then don’t. I’m more the one who said “I can’t draw” and then went ahead and drew anyway.

All those activities, but especially programming, can consume my attention, and suffuse me with a general feeling of joy. Not a big ecstatic kind of rush joy, just an ongoing feeling that this is good. I imagine, but cannot know, that it’s the same kind of feeling a musician gets making music, an artist gets when the painting os going well, … and the feeling in the potter as the vase takes on the shape the potter has in mind.

And in one way, code is “better” than most of those other forms. In all such endeavors, the maker can always do better. In drawing, painting, sculpting, one can generally only do better “next time”.

Apparently, according to the Internet, it was Paul Valéry who originated the notion that a work is never truly finished, only abandoned. The idea has been attributed to many, and I’ve quoted it in these pages a time or two.

But the thing with potting, sculpture, painting, furniture, drawing, most forms, we typically can’t go back and improve the thing, we can only do another thing. With writing, prose or poetic, we can go back and improve the thing, but once it’s published, well, writing a new thing seems better.

What I love about code, about programming, is the feeling of the program changing under my hands. There are many aspects to making a program, as there are to any more classical form of art or craft. I imagine that typically, the maker really enjoys some aspects, and others not so much. If they’re fortunate, they enjoy more aspects. A truly lucky person would enjoy every aspect of their work. I don’t know of anyone like that and I, for one, do not enjoy all the aspects.

I mostly enjoy just two programming aspects. I enjoy starting from zero or near zero and coming up with the solution to some problem. And I enjoy looking at code, seeing how it could be improved, and improving it.

The truly marvelous thing about my code, and almost all the code I’ve ever seen, is that there is plenty of room for improvement. Especially with my code.

I look at my code; I think “that’s horrid, what fool did that?”; I forgive the fool—he probably had other things on his mind; and I joyfully improve what I’ve found.

A thing that I do not enjoy is a long slog. I especially don’t enjoy a long slog with the program broken. So, driven by long experience, and driven by GeePaw Hills “Many More Much Smaller Steps” notion, I find ways to improve the program in tiny steps, working mostly from green to green. The result is that the longest drab slog becomes instead a series of joyfully coming up with little solutions, and joyfully improving code.

And that … is why I do this.

Why do I tell you about it? Well, mostly for similar reasons. I like to try to share my joy, and this is the medium in which I can do it. If someone reads these words, great. If they then try to find ways to increase their own joy, greater still.

Find your joy. There must be a pony in here somewhere.

Hello, loves!

Writing a note to ask for ideas, I got an idea. Let’s see what happens with it. Result: I think it turns out nicely.

I was thinking about this morning’s creation of a little object that made things simpler and was easy to test. And I was looking at RoomView, and a long story test for something that doesn’t seem that tricky. And on Hill’s slack, I though I’d start a convo and get some advice, and I wrote:

A RoomView has a method illuminate that illuminates every cell that it contains. The RoomView is owned by the DungeonView, which has a list of illuminated cells, because when new content is added in game play, the content item needs to be illuminated or not depending on whether the cell it is being placed in is illuminated. The DungeonView knows the dungeon layout, since it runs the map and such. So a RoomView has a DungeonView … ah, there’s yer problem right there. Maybe we should just pass in the things the RoomView needs when it needs them, and then we could more readily test it by passing it fake things to talk to.

So let’s try to unhook the RoomView from knowing its owners, and in so doing, improve things a bit. Here’s the whole class:

class RoomView:
    def __init__(self, dungeon_view, room):
        self.dungeon_view = dungeon_view
        self.dungeon = dungeon_view.dungeon
        self.layout = self.dungeon.layout
        self.room = room
        self.sprites = []
        self.cell_sprites = dict()
        self.texture_finder = TextureFinder()
    def create_floor(self, shape_list):
        for cell in self.room:
            self.choose_flooring(cell, shape_list)
    def choose_flooring(self, cell, shape_list):
        texture = self.choose_flooring_texture(cell)
        sprite = self.make_adjusted_sprite(cell, texture)
        self.cell_sprites[cell] = sprite
        self.sprites.append(sprite)
        shape_list.append(sprite)
    def illuminate(self, center_cell, distance):
        for cell, sprite in self.cell_sprites.items():
            if cell.manhattan_distance(center_cell) < distance:
                self.dungeon_view.illuminate(cell)
                sprite.visible = True
    def make_adjusted_sprite(self, cell, texture):
        scale = scale_texture(texture)
        sprite = arcade.Sprite(texture, scale=scale)
        sprite.position = cell.center_position(cell_size)
        sprite.visible = False
        return sprite
    def choose_flooring_texture(self, cell):
        borders: BorderList = self.layout.get_borders(cell)
        border_type = borders.border_string()
        name = self.texture_finder.full_name(border_type)
        return arcade.load_texture(name)

The only user of layout is the last method (and a test). The only use of Dungeon is to get the layout. There is another use of the DungeonView inn illuminate. Let’s get rid of all three of those members.

First change signature of create_floor to require the layout as a parameter.

    def create_floor(self, layout, shape_list):
        for cell in self.room:
            self.choose_flooring(cell, shape_list)

I defaulted the new parameter to self.layout, and since the caller is DungeonView, it works. Tests are green. We could commit. Let’s do, just because we can. Commit: disconnecting RoomView from the universe.

Now change signature of choose_flooring:

    def choose_flooring(self, layout, cell, shape_list):
        texture = self.choose_flooring_texture(cell)
        sprite = self.make_adjusted_sprite(cell, texture)
        self.cell_sprites[cell] = sprite
        self.sprites.append(sprite)
        shape_list.append(sprite)

Green. Commit. Now change signature of choose_flooring_texture and remove the reference to self.layout.

Green. Commit. Now remove two member variables, dungeon and layout:

class RoomView:
    def __init__(self, dungeon_view, room):
        self.dungeon_view = dungeon_view
        self.room = room
        self.sprites = []
        self.cell_sprites = dict()
        self.texture_finder = TextureFinder()

I expect this to break a test and it does. The fix is to change this line in the test:

        borders = view.layout.get_borders(c_33)

To this:

        borders = layout.get_borders(c_33)

Green. Commit. Now for illuminate:

class RoomView:
    def illuminate(self, center_cell, distance):
        for cell, sprite in self.cell_sprites.items():
            if cell.manhattan_distance(center_cell) < distance:
                self.dungeon_view.illuminate(cell)
                sprite.visible = True

This wants a dungeon_view parameter. Change signature and remove the self:

    def illuminate(self, dungeon_view, center_cell, distance):
        for cell, sprite in self.cell_sprites.items():
            if cell.manhattan_distance(center_cell) < distance:
                dungeon_view.illuminate(cell)
                sprite.visible = True

A test fails. I am not surprised but hadn’t looked to see if one would. This line:

    def test_room_view_illuminate(self):
        ,,,
        room_view.illuminate(self, Cell(12, 12), 3)

Needs to be:

    def test_room_view_illuminate(self):
        ,,,
        room_view.illuminate(dungeon_view, Cell(12, 12), 3)

Green. Commit.

We can remove the saving of the dungeon_view instance variable:

class RoomView:
    def __init__(self, dungeon_view, room):
        self.room = room
        self.sprites = []
        self.cell_sprites = dict()
        self.texture_finder = TextureFinder()

Green. Commit. Change signature on the init:

class RoomView:
    def __init__(self, room):
        self.room = room
        self.sprites = []
        self.cell_sprites = dict()
        self.texture_finder = TextureFinder()

Green. Commit.

Reflection

We have removed three instance variables from RoomView, which were pointers that wired the class into everything around it. Now it is not wired to any other object, and when it needs information from or to send messages to another object, that object is passed to it on the relevant call. It is notably simpler.

PyCharm highlights this method as static, which is generally a hint of Feature Envy:

    def make_adjusted_sprite(self, cell, texture):
        scale = scale_texture(texture)
        sprite = arcade.Sprite(texture, scale=scale)
        sprite.position = cell.center_position(cell_size)
        sprite.visible = False
        return sprite

I don’t see a place we’d rather have the method. scale_texture is a method in ‘params.py’. We could move this method there, which would at least get it out of here. Let’s do that. Move it and edit in params:

params.py
def make_adjusted_sprite(cell, texture):
    scale = scale_texture(texture)
    sprite = arcade.Sprite(texture, scale=scale)
    sprite.position = cell.center_position(cell_size)
    sprite.visible = False
    return sprite

Change the call:

    def choose_flooring(self, layout, cell, shape_list):
        texture = self.choose_flooring_texture(layout, cell)
        sprite = params.make_adjusted_sprite(cell, texture)
        self.cell_sprites[cell] = sprite
        self.sprites.append(sprite)
        shape_list.append(sprite)

Green. Commit: move make_adjusted_sprite to params.

Reflection

RoomView is now vastly simplified:

class RoomView:
    def __init__(self, room):
        self.room = room
        self.sprites = []
        self.cell_sprites = dict()
        self.texture_finder = TextureFinder()
    def create_floor(self, layout, shape_list):
        for cell in self.room:
            self.choose_flooring(layout, cell, shape_list)
    def choose_flooring(self, layout, cell, shape_list):
        texture = self.choose_flooring_texture(layout, cell)
        sprite = params.make_adjusted_sprite(cell, texture)
        self.cell_sprites[cell] = sprite
        self.sprites.append(sprite)
        shape_list.append(sprite)
    def illuminate(self, dungeon_view, center_cell, distance):
        for cell, sprite in self.cell_sprites.items():
            if cell.manhattan_distance(center_cell) < distance:
                dungeon_view.illuminate(cell)
                sprite.visible = True
    def choose_flooring_texture(self, layout, cell):
        borders: BorderList = layout.get_borders(cell)
        border_type = borders.border_string()
        name = self.texture_finder.full_name(border_type)
        return arcade.load_texture(name)

Thirty lines, down from 40. No connection to substrate classes. We may or may not simplify its tests, but we certainly could if we chose to.

It’s not perfect, and it’s easier to see some flaws. Most significant issues include:

1. It’s arguably not a view: it neither draws nor receives input from the model.
2. It clearly has two entirely separate responsibilities: it creates flooring for the room’s cells, and it illuminates cells within the room.

This makes me suspect that we have, at best, some kind of conglomerate RoomUtilityFunctionCollection, and quite possibly two separate tiny classes, a RoomIlluminator and a FlooringSelector, or something like that.

But for now, we have made notable improvements, so let’s sum up.

Summary

Here, we observed a class that had accumulated links to the DungeonView, the Dungeon (which it really didn’t need) and to the DungeonLayout. No one deserves that much explicit connectivity. Removing the object’s links and passing in reference objects only as needed reduces coupling substantially, at no cost in additional code, merely changes to calling sequences and subsequent references to parameters instead of instance variables.

It may not be worth it to go back and retrofit the tests, but I’d wager that we can write much simpler tests for RoomView now than we currently have.

I wonder … the Cell now knows how to access the layout, which it does through a Cell class variable. Right now, we don’t make use of that link, but we could. Probably not a good idea: still better to pass it where it’s needed.

Or maybe there are new methods that could be added to Cell that would be helpful. We’ll keep an eye out for that, but we want not to overload Cell with things that don’t really pertain to it. But worth keeping in mind.

Bottom line: a noticeable improvement and very easy to accomplish. Something to think about.

See you next time!

Hello, loves!

Received wisdom and personal experience tell me to cover built-in collections. Here’s why.

Back in the day, my betters would rabbit on about “never” using build-in collections directly, saying that it was “always” better to write a little class holding the collection we wanted. I myself have learned that lesson time and time again. It is my fashion to learn things over and over, because I tend to make the same mistakes over and over.

In favor of the built-in collection, especially in Python, we have a strong argument: laziness. Almost anything you want to do with a collection, Python has a custom-made object or function to do the job. And, as we’ll see in a moment, even the straightforward things seem to invite “just” using a built-in collection. And, as always, the word “just” has a lot hiding behind it.

Let’s get to the case. Yesterday we were working on improving our notation for dealing with textures, so that instead of some horrendous path name, we could just say ‘lever/1.png’ and the right texture would be found. Although I had not know it going in, I found that arcade allows defining a “resource handle”, and we wound up with this code:

class ContentView:
    error_texture = ':resources:images/items/star.png'
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.error = False
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        for resource in resources:
            try:
                texture = arcade.load_texture(':ron:'+resource)
            except (FileNotFoundError, AttributeError):
                self.error = True
                texture = arcade.load_texture(self.error_texture)
            self.sprite.append_texture(texture)
        assert not self.error
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

The new bit is just the arcade.load_texture(':ron:'+resource), because over in DungeonView, we did this:

    def setup_assets(self):
        arcade_resources = ':resources:images/items/'
        arcade_resources = arcade.resources.resolve(arcade_resources)
        my_resources = '/Users/ron/Desktop/DungeonTiles/png/objects/'
        arcade.resources.add_resource_handle('ron',arcade_resources)
        arcade.resources.add_resource_handle('ron',my_resources)

That defines a “handle” ‘:ron:’ that directs arcade to search those two folder for file names and short paths like lever/1.png. The result is that all arcades built-in textures, and all of my purchased ones, can be easily found.

So far so good. Our plan included caching the textures. The code above loads the texture every time we use it, so if we put a dozen chests in the dungeon, we’ll read the file a dozen times. Tacky.

So yesterday, while you were away, I did this:

class ContentView:
    error_texture = arcade.load_texture(':resources:images/items/star.png')
    known_textures: dict[str, arcade.Texture] = dict()
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.error = False
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        for resource in resources:
            texture = self.get_texture(resource)
            self.sprite.append_texture(texture)
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)
    def get_texture(self, resource):
        if resource in self.known_textures:
            return self.known_textures[resource]
        try:
            texture = arcade.load_texture(':ron:' + resource)
            self.known_textures[resource] = texture
        except (FileNotFoundError, AttributeError):
            self.error = True
            texture = self.error_texture
        return texture

When we create a new ContentView, we pass it the resource names that it should have, and, looping over get_texture, we append them to the item’s sprite. In get_+texture, we just check the class-level dictionary known_textures, returning what we find if it is there, and otherwise loading it and putting it in the dictionary.

Pretty standard little cache of name->texture. It took less time to do than it just took to explain it.

So, I don’t know why, I was thinking about what I’d done and some voice said something to me about covering native collections, and I started to answer why this case was so simple that the guideline didn’t apply, when I realized that, well actually, a little object of our might be better. So I decided to find out. So let’s find out.

There are only four methods in ContentView other than __init__: get_texture, illuminate, remove, and set_state. The latter three refer to things we do at run time, we light up the object, we animate it, and we can remove it when it is destroyed or given to Dot.

The method get_texture isn’t like that. And it is as long as the other three methods combined.

The Plan

To resolve this tension, we’re going to create a very small object, TextureCache, and use it. I think we’ll just create it where the current dict is, in the class variable known_resources.

I’m not sure how good our tests are for this class, so we’ll start by putting None into the known_textures just to see if anything breaks. If not, we’ll code something that does.

Two tests fail:

    def test_creation(self):
        resource = 'keyRed.png'
        factory = ContentFactory()
        item = factory.decor(name='key', resource=resource, scale=0.5)
        cell = Cell(0,0)
        view = ContentView(cell, item, item.resources)
        assert view.sprite.visible == False
    def test_content_view_uses_ron_handle(self):
        layout = DungeonLayout()
        dungeon = Dungeon(layout)
        dv = DungeonView(dungeon, testing=True) # inits handle
        resource = 'Skeleton1.png'
        content = ContentFactory().decor(name='test', resource=resource, scale=0.5)
        cv = ContentView(Cell(5,5), content, content.resources, content.scale)
        assert not cv.error

That’s good. But I think we’d like to TDD this tiny class anyway, trivial though it is. Why? Because I want to be sure it’s really caching. The code we have now could have a defect in it that caused it never to find anything, and we’d never realize that it was reading a file every time.

class TextureSaver:
    def __init__(self):
        pass
class TestTextureSaver:
    def test_exists(self):
        cache = TextureSaver()

I decided to name it TextureSaver. We’ll discuss why below. Green so far, let’s commit: working on TextureSaver.

I figure this test will do for us:

    def test_saves(self):
        DungeonView.setup_assets()
        cache = TextureSaver()
        r1 = 'lever/1.png'
        r2 = 'lever/2.png'
        t1 = cache.get(r1)
        t2 = cache.get(r2)
        assert len(cache) == 2
        t3 = cache.get(r1)
        assert t3 == t1
        assert len(cache) == 2

We’ll need some code:

class TextureSaver:
    error_texture = arcade.load_texture(':resources:images/items/star.png')
    def __init__(self):
        self._cache:dict[str, arcade.Texture] = dict()
        self.error = False
    def __len__(self):
        return len(self._cache)
    def get(self, resource_name:str) -> arcade.Texture:
        if resource_name in self._cache:
            return self._cache[resource_name]
        try:
            texture = arcade.load_texture(':ron:' + resource_name)
            self._cache[resource_name] = texture
        except (FileNotFoundError, AttributeError):
            self.error = True
            texture = self.error_texture
        return texture

Test passes. No real surprise, we basically just moved the code over. Commit.

But now in ContentView:

class ContentView:
    textures = TextureSaver()
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.error = False
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        for resource in resources:
            texture = self.textures.get(resource)
            self.sprite.append_texture(texture)
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

We can remove the error texture, and the get method we used to have. Tests all green. Commit.

So this is already good, because now ContentView doesn’t know anything about how to cache textures.

Let’s rename that class to TextureProvider. And we might rename it again.

class ContentView:
    textures = TextureProvider()
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.error = False
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        for resource in resources:
            texture = self.textures.get(resource)
            self.sprite.append_texture(texture)
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

Why are we pulling textures out of that one object and stuffing them into another? Let’s have TextureProvider do that job:

class ContentView:
    textures = TextureProvider()
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.error = False
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        self.textures.load_sprite(self.sprite, resources)
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

And tests break, but then:

class TextureProvider:
    def load_sprite(self, sprite, resource_names):
        for resource_name in resource_names:
            texture = self.get(resource_name)
            sprite.append_texture(texture)

Why do we bother to create the sprite and pass it in? Let’s have the provider do that too.

class ContentView:
    textures = TextureProvider()
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.error = False
        self.cell = cell
        self.item = content_item
        self.sprite = self.textures.load_sprite(resources)
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

And:

    def load_sprite(self, resource_names):
        sprite = Sprite()
        for resource_name in resource_names:
            texture = self.get(resource_name)
            sprite.append_texture(texture)
        return sprite

Commit. Let’s review the whole TextureProvider class:

class TextureProvider:
    error_texture = arcade.load_texture(':resources:images/items/star.png')
    def __init__(self):
        self._cache:dict[str, arcade.Texture] = dict()
        self.error = False
    def __len__(self):
        return len(self._cache)
    def load_sprite(self, resource_names):
        sprite = Sprite()
        for resource_name in resource_names:
            texture = self.get(resource_name)
            sprite.append_texture(texture)
        return sprite
    def get(self, resource_name:str) -> arcade.Texture:
        if resource_name in self._cache:
            return self._cache[resource_name]
        try:
            texture = arcade.load_texture(':ron:' + resource_name)
            self._cache[resource_name] = texture
        except (FileNotFoundError, AttributeError):
            self.error = True
            texture = self.error_texture
        return texture

Now it seems to me that the get method is essentially private now, as our only user now uses load_sprite. We may have other users later but this tiny class only has one user other than its tests. So we’ll make it private until we need it, if we ever do. Commit again.

What is the name of this class now? Is it still TextureProvider? Or is it a SpriteLoader? TexturedSpriteMaker? SpritePainter? SpriteTexturator? LordHighTexturizerOfSprites?

I’m not sure. We’ll sit with this name for a while. Let’s assess what we’ve done.

Reflection

We have simplified ContentView and reduced its responsibilities. It used to have two classes of behavior, managing sprites at run time, and creating a sprite with multiple textures. It now has just the former group. It is down from 4 concrete methods to 3. It has one fewer class variables. It orders out to get its sprite instead of building one itself. It’s much simpler.

The TextureProvider is a new class, and it is 27 lines long, while we have “only” removed 15 lines from ContentView. We have a net increase in code of about a dozen lines!!!

TextureProvider encapsulates a concept that we didn’t have in the code before, loading a Sprite, which was formerly represented by a loop in one method and another method that did the texture getting bits. So it adds to clarity.

The flow of things is interesting.

At first, we were just covering the cache dictionary with a little object, which was sufficient to move the nasty get method out of ContentView, where it was clearly out of place. But having done that, it slowly became clear that the new object could be more helpful, first by adding a texture to a sprite for us, and then we saw that it could provide the whole Sprite.

And here is what may be the most important thing: this tiny new object is easy to test. We don’t have to set up layouts and dungeons and whatnot. We just create it and it’s ready to test.

I’ve been whining about the difficulty of testing things in this program. If I hadn’t written every line myself I’d be raging at whatever fool made it so hard to test. This experience of creating a cover for a collection making things easier to understand and much easier to test … this experience that I have had innumerable times over many years … revitalizes my attention to such things. If this high sticks, maybe we’ll look for other places to make things better with tiny objects.

Or maybe I’ll just forget and fall back into old bad habits. It could happen.

Summary

A tiny object improves the code that uses it, and creates opportunities for adding small bits of capability that makes things better. And it’s easy to test! Yummy!

See you next time!

Postscript

I was going to tell you why TextureCache got renamed: There is an arcade class named TextureCache. It’s not the same as what we did today, but I didn’t want o hide the name, in case we ever need the arcade one.

Hello, loves!

Resource designation is awkward, and I think we’re loading them multiple times. Let’s see what we can do about this. Arcade helps out!

Here’s the sort of thing we have to put up with:

class ContentFactory:
    def lever(self, *, name):
        def lever(self, interactor):
            self.state = (self.state+1)%len(self.resources)
            interactor.publish('control', self.name, state=self.state)
            interactor.publish('state_number', self.name, content=self, state=self.state)
            return False
        resource1 = '/Users/ron/Desktop/DungeonTiles/png/objects/lever/1.png'
        resource2 = '/Users/ron/Desktop/DungeonTiles/png/objects/lever/2.png'
        resource3 = '/Users/ron/Desktop/DungeonTiles/png/objects/lever/3.png'
        resource4 = '/Users/ron/Desktop/DungeonTiles/png/objects/lever/4.png'
        resources = [resource1, resource2, resource3, resource4]

Sometimes I’ve resorted to a temp, only slightly less irritating:

main.py
    ...
    resources=':resources:images/items/'
    my_resources = '/Users/ron/Desktop/DungeonTiles/png/objects/'
    factory = ContentFactory()
    item = factory.receivable(name ="a red key", resource=resources + 'keyRed.png', scale=0.5)   cell = Cell(29, 28)
    cell.add_content(item)
    ...

Now here chez Ron that’s not all that irritating, since I don’t really use a lot of resource strings, but if we were a real team building a real game, there would be ResourceMasters creating and using lots of different files. And even here, if and when I decide to flesh this game out a bit — and very likely I will — it can only get more irritating.

So let’s see what some goals might be for improvement.

1. Load a given resource only once;
2. Provide a short notation for resources,
   perhaps like ‘keyRed’ or ‘/lever/1’;
3. Possibly allow or require the file type suffix;
4. Ideally, require no changes to existing code;
5. Failing that, require only minimal changes such as removing the path bits;
6. Remember to deal with the floor tile resources, not just content.

We’d better look at the code for processing resources now.

The action will take place in ContentView, where we load all the textures from the provided strings.

class ContentView:
    error_texture = ':resources:images/items/star.png'
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        for resource in resources:
            try:
                texture = arcade.load_texture(resource)
            except (FileNotFoundError, AttributeError):
                texture = arcade.load_texture(self.error_texture)
            self.sprite.append_texture(texture)
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

There’s yer problem right there! We expect a full path name here, and we unconditionally call arcade.load_texture on it. We even load the error texture every time.

I’ve taken a quick look at flooring, which uses a thing called TextureFinder and while it could use some improvement, I think it is more likely to be a use of our new capability than a part of it. So we’ll try to meet our goals above with some new code.

Design Thinking

So. An object that takes a short name such as ‘lever/1.png’, or even ‘lever/1’ if we can see how to do it, and returns a loaded texture by that name if it exists and a standard error texture if it can’t be found. (We don’t allow our code to crash.)

There are two kinds of paths to resources supported by arcade:

    resources=':resources:images/items/'
    my_resources = '/Users/ron/Desktop/DungeonTiles/png/objects/'

So far, the only way I know to process those colon ones is with arcade.load_texture. We want to cache the textures. I guess we could do that, keyed on the short name and trying all the paths we know. That might be good. It might also be good to know if arcade will resolve that colon thing into an actual path for us.

RTFM! Amazing What You Can Find!

A bit of searching in the arcade documents offers a method that lists all built-in assets. Let’s try it out.

    def test_path(self):
        p1 = '/Users/ron/Desktop'
        assert Path(p1).exists()
        p1_r = arcade.resources.resolve(p1)
        assert Path(p1_r).exists()
        p2 = ':resources:images/items/'
        assert not Path(p2).exists()
        p2_r = arcade.resources.resolve(p2)
        assert Path(p2_r).exists()

So there is the answer to one question, how we convert a colon path to a real one?

Let’s see that list. It is immense. This test limiting to image files with key in their name:

    def test_assets(self):
        assets =  arcade.resources.list_built_in_assets(name='key', extensions=['.png', '.jpg', '.jpeg'])
        p_assets = '\n'.join(str(a) for a in assets)
        print(p_assets)
        assert False

Provides 15 lines that look like this:

/Users/ron/PycharmProjects/dungeon/.venv/lib/python3.12
/site-packages/arcade/resources/assets/images
/items/keyGreen.png

I also learn that there is a way to provide one’s own resource handle. After a bit of messing about this test runs:

    def test_resource_handle(self):
        base = '/Users/ron/Desktop/DungeonTiles/png/objects/'
        resolved = Path(base).resolve()
        arcade.resources.add_resource_handle('ron',
                    resolved)
        path = arcade.resources.resolve(':ron:lever/1.png')
        assert str(path) == base + 'lever/1.png'

I think that means that if I were to add the right resource handles, we could use shorter names. That would be nice.

After a bit more reading I find that I don’t have to resolve the path. This works:

    def test_resource_handle(self):
        base = '/Users/ron/Desktop/DungeonTiles/png/objects/'
        arcade.resources.add_resource_handle('ron',
                    base)
        path = arcade.resources.resolve(':ron:lever/1.png')
        assert str(path) == base + 'lever/1.png'

I had a test fail that made me think I needed to do that but it must have been due to a typo or something.

I wonder if it will now resolve without providing the handle. No. Apparently resolve doesn’t try all the handles. Is there some way to do that? We can add multiple directories under one handle, and it will search all of them.

We only really use two paths currently:

    resources=':resources:images/items/'
    my_resources = '/Users/ron/Desktop/DungeonTiles/png/objects/'

Can’t we make a single resource handle for both those? Let’s try another test.

    def test_combined_handle(self):
        resources = ':resources:images/items/'
        arcade_resources = arcade.resources.resolve(resources)
        my_resources = '/Users/ron/Desktop/DungeonTiles/png/objects/'
        arcade.resources.add_resource_handle('ron',arcade_resources)
        arcade.resources.add_resource_handle('ron',my_resources)
        lever = arcade.resources.resolve(':ron:lever/1.png')
        keyRed = arcade.resources.resolve(':ron:keyRed.png')

This test fails if it can’t resolve those resources, and it passes. So I’ve created a single handle ‘:ron:’’ that can point to all our resources.

That, alone, resolves one of our goals, a more convenient notation. Let’s change main to assume that it can use ‘:ron:’ and make it work. We’ll start with a test.

My plan is that DungeonView, which it starts up, will register the handle and paths. Then when a ContentView goes for a resource, it should always be able to find it. I’m not sure what it’ll take. We’ll make the test work, learning how along the way.

    def test_content_view_uses_ron_handle(self):
        layout = DungeonLayout()
        dungeon = Dungeon(layout)
        dv = DungeonView(dungeon, testing=True) # inits handle
        resource = ':ron:Skeleton1.png'
        content = ContentFactory().decor(name='test', resource=resource, scale=0.5)
        cv = ContentView(Cell(5,5), content, content.resources, content.scale)

This fails because the handle isn’t defined yet, by DungeonView, which needs to be enhanced:

    def setup_assets(self):
        arcade_resources = ':resources:images/items/'
        arcade_resources = arcade.resources.resolve(arcade_resources)
        my_resources = '/Users/ron/Desktop/DungeonTiles/png/objects/'
        arcade.resources.add_resource_handle('ron',arcade_resources)
        arcade.resources.add_resource_handle('ron',my_resources)

I call that in the init. Test passes, which tells us that the ContentView’s load_texture accepts the handle.

But let’s make it harder. Let’s not mention the handle, so that our users can just name the short path and file that they want.

I am mistaken. ContentView, because we cannot crash, recovers if it cannot find the file specified.

class ContentView:
    error_texture = ':resources:images/items/star.png'
    def __`init`__(self, cell, content_item, resources, scale=0.5):
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        for resource in resources:
            try:
                texture = arcade.load_texture(resource)
            except (FileNotFoundError, AttributeError):
                texture = arcade.load_texture(self.error_texture)
            self.sprite.append_texture(texture)
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

I could just make this work: I think I know exactly what needs to be done. Let’s add an error flag to CntentView:

class ContentView:
    error_texture = ':resources:images/items/star.png'
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.error = False
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        for resource in resources:
            try:
                texture = arcade.load_texture(resource)
            except (FileNotFoundError, AttributeError):
                self.error = True
                texture = arcade.load_texture(self.error_texture)
            self.sprite.append_texture(texture)
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

Now my test can check the flag.

    def test_content_view_uses_ron_handle(self):
        layout = DungeonLayout()
        dungeon = Dungeon(layout)
        dv = DungeonView(dungeon, testing=True) # inits handle
        resource = 'Skeleton1.png'
        content = ContentFactory().decor(name='test', resource=resource, scale=0.5)
        cv = ContentView(Cell(5,5), content, content.resources, content.scale)
        assert not cv.error

Test fails as anticipated. Fix ContentView to add the ‘:ron:’ internally.

        for resource in resources:
            try:
                texture = arcade.load_texture(':ron:'+resource)
            except (FileNotFoundError, AttributeError):
                self.error = True
                texture = arcade.load_texture(self.error_texture)

Now I think the entire game will break until we fix up main. It does:

ValueError: Invalid resource handle 'ron::resources:images/items/keyRed.png'

In main we need to change things like this:

    appearing = factory.appearing(name='a brilliant torch', resource=my_resources + 'torch/1.png', scale=1)
    cell9 = Cell(36, 29)
    cell9.add_content(appearing)

To this

    appearing = factory.appearing(name='a brilliant torch', resource='torch/1.png', scale=1)
    cell9 = Cell(36, 29)
    cell9.add_content(appearing)

And similarly in the ContentFactory. The game works. But there are tests that are using the long form. Let’s make them break:

class ContentView:
    error_texture = ':resources:images/items/star.png'
    def __init__(self, cell, content_item, resources, scale=0.5):
        self.error = False
        self.cell = cell
        self.item = content_item
        self.sprite = Sprite()
        for resource in resources:
            try:
                texture = arcade.load_texture(':ron:'+resource)
            except (FileNotFoundError, AttributeError):
                self.error = True
                texture = arcade.load_texture(self.error_texture)
            self.sprite.append_texture(texture)
        assert not self.error
        self.sprite.set_texture(0)
        self.sprite.visible = False
        self.sprite.scale = scale_texture(self.sprite.textures[-1], scale)

I am somewhat surprised. I expected tests to be providing parameters that couldn’t resolve. Find all the users of ContentView and look. There was one referring to the old ‘:resources:’ path. We will probably discover, in the future, that assuming everything can be found under ‘:ron:’ isn’t quite right. If we do discover that, we’ll deal with it. Dealing with it now would be possible but speculative.

I’ll remove the assert from ContentView but retain the error flag. Commit: ContentView assumes resources are in the handle :ron:

Let’s sum up.

Summary

I wasn’t aware of how the :resource: things worked in arcade, but a bit of Reading of The Fine Manual (RTFM) taught me enough so that I could fumble my way to a single resource handle, :ron:, that points to my desktop folders, which are good enough for now, and the built-in assets that we use. So now any short-path file name will search both those folders, my desktop first, and all the file names in the system are now simple file names, or minimally prefixed like ‘lever/1.png’.

We changed DungeonView, as the first and topmost class that cares about images, to define our new handle to arcade. Then ContentView helpfully prefixes incoming resource short-path names with :ron: and resolves and loads the texture.

In our next phase, we’ll build a little cache of some kind so as to load textures only once. And at some future date, we should look at doing something similar for the flooring, which has a lot of reuse of the same tiles over and over.

A little learning, a little code, and how the references to resources are much more convenient. And we’re in a perfect position to cache them so as only to load them once.

Nice. Not bad at all. See you next time!

Hello, loves!

Sweet little idea … I have one. Very small but I think it’ll make things just a bit nicer. We’ll see.

I’ve been improving the code both in the last few articles and sometimes when you weren’t watching. If there has been a theme to the work, it has been to move responsibility for things to the places where they seem to fit better. Something something cohesion. I know—or used to know—all that theory, but these days I follow much simpler practices, removing duplication, observing Feature Envy and moving code to the class we’ve been fondling a bit too much, and so on.

Much of what I’ve done the past few days has added capability to Cell class. I think it’s worth mentioning how that works, since a Cell knows essentially nothing:

class Cell:
    def __init__(self, x, y):
        self._xy = (x,y)

A Cell is just a tuple with delusions of grandeur, because it can do many things. Its methods include add_content, attempt_move, available_neighbors, can_move_to, center_position, contents, creating, distance, has_passage, is_available, is_in_a_room, layout, manhattan_distance, neighbors, offset_by, randomized_neighbors, remove_content, room, vector_diff, x, xy, y.

How can an object containing just x-y coordinates do all that? It’s a bit tricky, but I think not too tricky, considering the power it gives us.

During game execution, all the Cell instances are stored in the DungeonLayout, which includes data structures for associating content with cells, for adding content, for allocating cells, creating rooms and so on. DungeonLayout creates all the Cells that will ever exist during the game . It creates them with Cell(x,y), and stores them in a dictionary indexed by (x,y).

Once that is done, if any code creates Cell(x,y), they get, not a new Cell, but the one that the layout created. It goes like this:

class DungeonLayout:
    def __init__:
        ...
        self._create_cells(max_x, max_y)
        ...
    def _create_cells(self, max_x, max_y):
        with Cell.creating(self):
            Cell.layout = None
            for x in range(max_x):
                for y in range(max_y):
                    self.cells[(x, y)] = Cell(x, y)
    # cell access

    def _at_xy(self, xy):
        return self.cells.get(xy, None)

Meanwhile, Cell has these methods:

class Cell:
    layout = None
    @classmethod
    @contextmanager
    def creating(cls, layout):
        Cell.layout = None
        try:
            yield
        finally:
            Cell.layout = layout
    def __new__(cls, x, y):
        if cls.layout:
            # noinspection PyProtectedMember
            return cls.layout._at_xy((x,y))
        else:
            return super().__new__(cls)
    def __init__(self, x, y):
        self._xy = (x,y)

creating is what Python calls a context manager. It’s commonly used to open a file and return it for subsequent use, guaranteeing that it’ll be closed when the calling code exists the with block.

In this case, we clear Cell’s class variable layout and yield, dropping into the double loop in _create_cells. When that code creates a Cell, we enter Cell.__new__ and discover that there is no layout, so we create the Cell, and return it. The super()--new__ runs the __init__ and we have a brand new cell, which DungeonLayout duly tucks away.

When that creation loop ends, the context manager code puts the DungeonLayout instance into its class member layout.

The effect of all that is that after DungeonLayout creates all the Cells, any time we say Cell(x,y), the __new__ code runs, finds cls.layout, and instead of creating yet another Cell, returns the one that is already in DungeonLayout.

From the viewpoint of a Cell, we now have access to the layout that contains the Cell. Individual cells do not contain a pointer to the layout, but the class does. So inside Cell code, self.layout will return the current layout. And that’s how we can implement something like this:

class Cell:
    @property
    def room(self):
        return self.layout.get_room(self)
    @property
    def is_available(self):
        return self.room is None
    @property
    def is_in_a_room(self):
        return self.room is not None

In our code, if we want to know a Cell’s room, or whether it is available, we just ask it. Inside the works, that turns into a lookup inside the layout, which has enough information to answer the question.

The result is much more readable code, since all the layout.contents_at(cell) kind of thing is expressed as cell.contents(). And much of what I’ve been doing over the past few days has been moving little methods into Cell,making the code all a bit more clear.

Isn’t that less efficient?

Yes. It is one method call more costly. Generally speaking, even in Python, which is notoriously slow, adding a single method dispatch is almost always negligible, unless it’s in a very long very tight loop. In practice, I would never hesitate to defer something rather than inline it, often even just for clarity. Here we get not just clarity but a simpler notation.

Today’s Idea

OK, that was then. What about now? I’m thinking about this method:

    def offset_by(self, offset):
        x,y = offset
        return Cell(x+self.x, y+self.y)

We use this method when we calculate neighbors, and occasional other times. And it’s just fine. Except that rather than this:

class Cell:
    def neighbors(self):
        return [neighbor
                for xy in [(-1, 0), (1, 0), (0, -1), (0, 1)]
                if (neighbor := self.offset_by(xy))]

I’d prefer to write this:

    def neighbors(self):
        return [neighbor
                for xy in [(-1, 0), (1, 0), (0, -1), (0, 1)]
                if (neighbor := self + xy)]

No biggie. I just like it better. Let’s make it so:

class Cell:
    def __add__(self, other):
        x,y = other
        return Cell(self.x+x, self.y+y)

Now we can change offset_by to use +.

    def offset_by(self, offset):
        return self + offset

Now we can inline offset_by. PyCharm fails to find two. I do them by hand. Remove the method. Commit.

Scanning Cell, I notice this:

class Cell:
    def vector_diff(self, target):
        return self.x - target.x, self.y - target.y

We could implement __sub__ and simplify the users of that method. It’s really only used here:

    def manhattan_distance(self, target):
        x,y = self.vector_diff(target)
        return abs(x) + abs(y)
    def distance(self, target):
        return math.hypot(*self.vector_diff(target))
    def vector_diff(self, target):
        return self.x - target.x, self.y - target.y

There is a test that uses it as well, though it didn’t really need to. I don’t think we get any mileage out of doing __sub__ and since the dunder methods are at least one layer down in the bag of tricks, I wouldn’t use them without a decent amount of returned value. Here, I don’t see it.

Summary

Same idea, a named method could be replaced by an arithmetic operator. In both cases, the operator would be used correctly. But in the one case I chose to do it, and in the other, I did not. The difference: adding the + capability impacted a bit more code and some of it was outside Cell. In the case of -, all the production code impacted is inside Cell itself, so no real expressive advantage materializes.

Bottom line, for me, a very small change, a small but non-zero code improvement, the program is just a bit easier to work with.

Worth it? If you’re a human, certainly. If you’re not a human (or some other kind of sentient biology-based organism) stop reading my site.

See you next time!

Postscript

class Cell:
    def attempt_move(self, direction):
        return self._get_connection_in_direction(direction).move()
    def _get_connection_in_direction(self, direction):
        return self._get_connection_offset(direction.value)
    def _get_connection_offset(self, offset):
        return self._get_connection(self + offset)

We can inline:

    def attempt_move(self, direction):
        return self._get_connection_in_direction(direction).move()
    def _get_connection_in_direction(self, direction):
        return self._get_connection(self + direction.value)

And inline again:

    def attempt_move(self, direction):
        return self._get_connection(self + direction.value).move()

Worth it? Maybe. I’m keeping it.

Hello, loves!

I have an on-line meeting that I can pay only small attention to. Herewith, a report on whatever tiny changes I find.

No plan This is just some time to spare, improving what I see. I’ll start from Dungeon, I think, but look to the views when Dungeon bores me.

Here is a method used only once other than by tests:

class Dungeon:
    # no longer in use?
    def set_player_position_with_interaction(self, cell):
        if self._interactions_allow_move(cell):
            self.just_set_player_position(cell)

It has something like seven tests, however. I think we’ll let it be.

There’s this method, which I used once and was proud of:

    def maker_flood(self):
        if len(self.flood_list) > 0:
            self.flood_list = SpriteList()
            return
        for cell, distance in (Flooder(layout=self.layout, origin=self.player_cell)
                .can_traverse()
                .flood()):
            cx, cy = cell.center_position(cell_size)
            text = arcade.create_text_sprite(text=str(distance),font_size=8)
            text.center_x = cx
            text.center_y = cy
            self.flood_list.append(text)

It fills the screen with numbers reflecting the distance of the cell from the current player position. It’s not useful just now but if w get into searching trouble, it may come in handy. We’ll preserve it.

This is awkward:

class Dungeon:
    def contents_at(self, cell):
        return self.contents[cell]

Dungeon maintains self.contents as a dict[Cell, list[Content]]. From a code-reading viewpoint, one would prefer cell.contents() or cell.contents. Cells, however, do not know the Dungeon, only the Layout. This may be hinting that contents should be a layout property. I think that would be a bit of an invasive change. But maybe not, if we “just” forwarded.

Let’s see how DungeonLayout would feel about that.

class DungeonLayout:
    def __init__(self, max_x=10, max_y=10):
        self.max_x = max_x
        self.max_y = max_y
        self.cells: dict[tuple[int, int], Cell] = dict()
        self._create_cells(max_x, max_y)
        self.rooms = []
        self.border_map:BorderMap|None = None
        self.passages: dict[tuple[Cell, Cell], bool] = dict()
        self.room_map: dict[Cell, Room] = dict()

Let’s change Dungeon here:

    def contents_at(self, cell):
        return self.layout.contents_at(cell)
    def place_content_at(self, cell, content):
        self.layout.place_content_at(cell, content)
    def run(self):
        self.layout.run_contents(self)
    def remove_content_from_cell(self, content, containing_cell):
        self.layout.remove_content_at(containing_cell, content)

That breaks 12 tests, no surprise there. In DungeonLayout

class DungeonLayout:
# contents

    def contents_at(self, cell):
        return self.contents[cell]
    def place_content_at(self, cell, content):
        self.contents[cell].append(content)
    def find_cell_containing_name(self, item_name):
        cell = None
        for candidate, items in self.contents.items():
            for item in items:
                if item.name == item_name:
                    cell = candidate
        return cell

We are green and the contents dictionary is gone from Dungeon. I find two more methods and they have no tests:

    def remove_content_from_cell(self, content, cell):
        self.contents[cell].remove(content)
    def run_contents(self, pub_sub):
        for cell, contents in self.contents.items():
            for content in contents:
                content.run(pub_sub)

That should be corrected. And we can do some convenience methods in Cell now. Possibly get rid of some of the forwarding.

This is enough for an afternoon’s idleness. Commit: moving contents handling to Layout. Forwarding in Dungeon is in for now.

Summary

Small steps, small improvements. Done over time, done all in a batch, doesn’t matter. Things improve. This is the way.

Postscript

Adding contents() as a method on Cell lets me remove Dungeon.contents_at entirely. I think a global replace or two might do the same for the remove method. We’ll leave that for another day.

See you soon!

Hello, loves!

Let’s see if I can tire myself out with code. I enjoy crafting code and ain’t no oligarch-feeding resource-consuming job-stealing computer program gonna take that away from me.

It’s 0030, I can’t sleep, so I’m going to code. We’ll begin with reviewing the responsibilities and connections of the various objects and layers that make up our design. I’ve been finding it hard to think about and work with and want to understand why. I suspect responsibilities in the wrong place, connections that aren’t right, the usual suspects.

Time Passes …

I annotated some dictionaries to make it more clear to me what’s in them. Then I moved about nine or ten methods out of DungeonLayout, the ones answering questions about cells, such as layout.is_available(cell) and the like. I provided similar methods and properties on Cell, such as cell.is_available. Those were all straightforward, although to finish the cleanup, I had to edit all the old versions to use the new versions. In a large system, that part could have been undertaken over time, with the layout ones deprecated. With everything in one repo and PyCharm at our fingertips, it was easy enough to do each one completely.

The result was to simplify DungeonLayout substantially, while the corresponding capabilities make more sense in Cell, and are usually a bit simpler as well. I’ll spare you the details. I believe that no test ever failed during this cycle. Certainly there was no significant trouble.

I got to bed at 0200 and slept uneventfully until 0830 or something like that.

Motivation

Of course I would not claim that I really understand why I do things, but certainly I have been thinking for some time that the DungeonLayout / Dungeon / DungeonView family are too complex and that there are aspects in at least some of those classes that should be pulled over to another of the family, or perhaps into helper classes. So simplifying is on my mind.

This Morning …

I plan to continue looking for ways to simplify and normalize the design. It’s high time, and there’s no one to say that I can’t.

One concern that I have has to do with Content, because a content item has a very substantial multiple personality. It has a presence in the Layout, in the sense that it is “in” a Cell. It has a presence in the Dungeon, in that Dot interacts with it when she moves, and the content item can even prohibit her from moving. It has a presence in the Views, in that its graphical representation resides in the sprite lists. And there is interaction among these roles.

Take Spikes, for example. They have three operating states, cycling, stopped up, and stopped down. They have two graphical states, up and down. When fully implemented, they will inconvenience Dot when up or running, and may even prohibit her from entering. They are controlled by another content item, which, when Dot bumps it, changes its own visible character, and publishes its state, which the spikes hear and use to change their own state.

Having told that story, I’m motivated to track through some of the code that is involved. Here’s the creation method:

class ContentFactory:
    def spikes(self, *, name):
        resource1 = '/Users/ron/Desktop/DungeonTiles/png/objects/trap/1.png'
        resource2 = '/Users/ron/Desktop/DungeonTiles/png/objects/trap/2.png'
        resources = [resource1, resource2]
        scale = 0.75
        cases = {
            0: (True, 0),
            1: (False, 1),
            2: (False, 0),
            3: (True, 0),
        }
        info = SimpleNamespace(cycling=True, cases=cases, time=0)
        def cycle(self, pub_sub, delta_time):
            if not self.info.cycling: return
            self.info.time += delta_time
            if self.info.time >= 1:
                self.info.time = 0
                self.state = (self.state+1)%len(self.resources)
                pub_sub.publish('state_number', self.name, content=self, state=self.state)
        cycle_sub = Subscription(event='on_update', caller_id='view', callback=cycle)
        def control(self, *, pub_sub, state):
            try:
                self.info.cycling, self.state = self.info.cases[state]
                pub_sub.publish('state_number', self.name, content=self, state=self.state)
            except KeyError:
                return
        control_sub = Subscription(event='control', caller_id=name, callback=control)
        return Content(name=name, resources=resources, scale=scale,
                       info=info, subs=[cycle_sub, control_sub],
                       )