Table of Contents

1 Corwin's Dungeon

This is my personal notes file for dungeon-mode. Below are the directions for the initial sprints of the project. The remainder of the document forms my contribution as toward delivering on that.

  1. (Dec 22 - Jan 5th) High Level Effort Guesstimation for both Interface Development and Manual Authoring. Task lists and estimates to this channel whenever and feel free to revise and extend your remarks. For extra credit, download GNU Emacs (I like Emax64 26.2 or 26.3 for Windows 10) and try making your notes using org mode.
  2. (Jan. 5th - Jan 19th) User journey and user story creation. What are the key user and system interactions? What orders may they occur in? How may this map to our interfaces (e.g. major and minor modes)? What tasks are needed to deliver that functionality and how long might all that take? Finally, considering both of the first two sprints, what items are "above the line" in the sense they should be assumed to be required to complete a minimum testable product. For extra credit in sprint two make org mode sort tasks based on priority (and dependencies?) and sum cost (time)

2 SYNOPSIS

My most current dungeon lives principally within a Google Docs spreadsheet, and should be fairly straight forward to convert to elisp statements. Deeper in the document I provide some design detail from spreadsheet in as much as this may suggest the key files or macros or whatever.

From a UI design perspective my focus, in terms of an initial MPTP for the first use-case, is getting a comfortable and familiar sense of graph paper and pencil, maybe high-lighter and felt-tipped markers.

In the remaining sections I'll rationalize these motivations further as then relate to key development tasks I think could factor into an Minimum Play-Testable Product (MPTP).

3 Initial Estimations

The section currently only contains information responding to sprint 1 e.g. user interface development and the manual authoring of content.

3.1 Interface Development

Tags Points
dungeon-mode 20
battle-board 10
baddie-board 5
map-mode 20
treasure-mode 10
character-mode 20
tables-mode 10
decent-mode 5
dungeon-master-mode 20
journal-mode 16

The remainder of the section forms initial task objective generally in the vein of user stories and any recomendations, analysis and notes which contributed..

3.1.1 Task Detail

  1. Create dungeon-mode (20 points)

    Oversee file interactions in terms of elisp expresisons. Use a queue and timer to insulate the command processing function. This package will not perform the file operations so this task must leap-frog or otherwise coordinate within initial development of 'dm-journal-mode'.

  2. Create dm-journal-mode (20 points)

    Create basic file-system interaction functions, (1) create an empty file associated to a given symbol, (2) given a symbol return file content, (4) read a file an index the symbols defined, (5) given a symbol return the file or file part where it is defined.

  3. Create dm-battle-board (20 points)

    Draw a party in terms of position and attributes. (body-hits, …) Provide a frame-work for font (e.g. ASCII, Unicode, …) based beautification. Make decorative content read-only.

  4. Create dm-baddie-board (5 points)

    Display baddies as viewed by the party or DM, e.g maybe no or limited health info per party's current view. It is fine to use hard-coded data if the REPL is not available.

  5. Create dm-map-mode (20 points)

    Display a map with a general store, corridor, and chambers behind secret doors and super-impose it over the data representation. Key constants may be hard-coded or implemented as vars however drawing must occur on-demand, must replace any existing image, and must include calculations of scale, a sizing factor from 0-4 which may be hard coded to 1 (100%) for the time-being.

  6. Create dm-treasure-mode (10 points)

    Display the treasure categories, including unresolved or undistributed treasure. Provide functions and key-map with bindings to (1) increment and (2) decrement numeric counters, (3) add or (4) remove an item from a list column, and to (5, 6) DWIM at point category at point. It is helpful but not required to select key bindings thoughtfully at this stage in development.

  7. Create dm-tables-mode (10 points)

    Display a sample of any of the common DM tables, e.g. spells. Use hard-coded data if the REPL isn't ready. Support basic cell-wise cursor movement with arrow keys. Highlight the cell under point. It is not required (but helpful) to include restriction of point to appropriate (interactive) spaces within the buffer.

  8. Create dm-character-mode (20 points

    Display a character sheet. Implement a reasonably well considered UI. Provide a key-map with minimal bindings for movement between sections.

  9. dm-decent-mode (5 points)

    Display a dired like interface of buffers important to dungeon-mode.

  10. dm-dungeon-master-mode (20 points)

    Prototype composite interface two working minor modes and the REPL. Note, while the REPL must be at least semi-functional to complete this task this will also provide a POC for dm-battle-board-mode proposed approach.

3.2 Analysis

Let's face-it. The user-interface is important. Not just to attracting others (whether to play, create, or contribute) but enjoyment of the game even for the most die-hard of us. Okay. Maybe not all.

Considering Emacs as the host environment for the game engine; however, may force (or strongly compel) some potentially key design decisions up front which otherwise it might make sense to wait for the stability of an optimization phase to address. This is because Emacs's facilities for interacting with the display manager (for such tasks as updating the display) are, while powerful, quite intrinsic to Emacs and for the most part we should probably not abstract them away.

For example, Emacs's system of character properties allows a feature (e.g. dungeon-mode) to mark individual characters and regions within a buffer with additional properties that provide feature specific information, usually display hints. Which installing functions there that will make case by case decisions about display rendering is, I think, normal, it would probably be a bad idea to e.g.: have an `dm-properties-manager' that attempts to control all of the properties installed across all of a given buffer as this might break core Emacs features and would likely also impact rendering performance meaningfully.

3.2.1 Recommendation: Rendering non-text content

In particular, a key decision along these lines is how to render out things like maps or the grids forming battle-boards, spellball-like inventory, and the rest. Because our needs are modest by game design standards –if not by those of typical Emacs Lisp projects– we have lots of options.

  • ASCII art

    • Sense of Style: nethack
    • Most obvious pro: easy
    • Most obvious con: seems limited

    I suspect this could be somewhat trivial to implement using text properties. Moreover, it adds no assets to our deliverable (e.g. jpg, ttf, etc. dungeon mode would require or distribute and maintain). That said it pretty much puts the visual aspects of the game into a small box, at least in so far as concerns native game-play within Emacs. Furthermore, if other design decisions have followed from and rely on this one, it may not be easy to bolt support for more sophisticated graphics display in-line onto the original modes. This concern, of course is universal to any option (and to most design decisions) however it's most significant when considering an alternative with clear performance, scalability, or stylist limitations.

  • Custom Fonts and Unicode

    • Sense of Style: loadrunner
    • Most obvious pro: easy
    • Most obvious con: still limited, now maybe with font files to manage

    As with the next option, the limitation here will be -given we create or utilize custom font-files- the need to create those in advance and distribute them with the game, provide details for collecting them from third parties, etc. That said, this is probably otherwise the rough level of effort as the ASCII option.

  • Tile packs

    • Sense of Style: gauntlet
    • Most obvious pro: easy way to get to pretty
    • Most obvious con: limited given the effort required

    This is just about as pretty as we can get to without drawing or rendering at the run-time. Here we create some number of image or sprite assets, most likely authoring them in-line with the game. As with the above options we are limited during game design and play to the visual presentations shipped with the game (notwithstanding you are presumably free to create your own).

  • Real-time display painting

    • Sense of Style: sheet of graph paper with felt-tip and pencil marks
    • Most obvious pro: we control the horizontal
    • Most obvious con: we might invent something

    As assumed in all the solutions we use likely use text properties to attach images (or ASCII art) however in this case rather than static images or image regions (e.g. of sprites) these properties point to functions which draw visual representations to overlay the raw information in the buffer on demand. Emacs provides native SVG commands, for example, which could be used to draw the stokes of the battle-board, etc., with other elements perhaps layered using z-index.

At the moment my leaning is toward the final option. While it forces some amount of close work to the front of the project this comes with more advantages than disadvantages:

  • Biggest Pros:
    • supports all the other options, functions can just return ACII or return an existing image/slice rather than drawing.
    • only option that presents an interface people might install Emacs to use.
  • Biggest Cons:
    • more upfront effort, at least vs ASCII or Unicode
    • puts upfront need on chucking out elisp vs create images whereas we currently have more artistic than programming skill represented in the project team.

Text and tile approaches all eventually back us into the corner of needing to know at game development time (or maybe dungeon-mode publication time) what display options will be possable. Let's turn Emacs into a fantastic looking thick client for RPGs that embraces rather than tries to escape their heritage of graph-paper and tally-marks.

Discussing these ideas we've settled on this plan for the MPTP:

  • map-mode overlay map code with SVG strokes, shapes, et. al.
  • battle-board and most if not all others use font-locked text

I did a little poking around following the above decision and didn't find any obvious means to put images under text that we still want the user to be able to work with in the buffer.

;; put some blank lines atop and emacs lisp scrach buffer
;; then see if you can get editable text into the circle
(let ((svg (svg-create 400 400 :stroke-width 10)))
       (svg-circle svg 200 200 100 :stroke-color "green")
       (put-image (svg-image svg) 0)
       ;;(remove-images 0 2000)
       )

Per TFM `put-image' is using an overlay added to a begin-text attribute of an overlay added into the text, to contain the image. This means that it's prepended to -but does not obscure- the text.

3.3 TODO Manual Data Entry

Create some notes on the potential approaches key tasks and respective LoE by early January, 2020.

4 Quick Notes on Data

We might be able to map key dungeon concepts to Emacs Lisp grouping syntax if we select our abstractions carefully:

dm abstract grouped by wut?
table () list wrap a victual or baddie table
map [] vector map are a list of these
(me . mine) ( . ) alist name something for later use
anything ' quote operate to include by ref

Table cells are just lists of sexp referencing or defining stuff. The expressions should result in a literal or a quoted expression. If an expression, it is to be resolved when the action token is in scope (e.g. at play-time) such that the REPL can be queried for information, e.g. about the character acting (if any), party, etc. The result of loading an individual table is a symbol containing references and expressions which compose one particular aspect of the game, say Spells e.g. treasure for wizards, which in combination with the definition statement for the spells table, provides enough information to resolve the event (notwithstanding dm-interactive and dm-interactable).

Inside map cells go the relationships to other map-cells and features such as secret doors. As discussed elsewhere these can likely be similar to text or overlay properties but are ultimately probably stored as plain data (e.g. the text description of the space, if any) with properties which contain any custom behaviour written for the map.

For general use items, for example items that could appear on more than one treasure table, we can use a-lists to create lists. By allowing an expression as both car and cadr we can potentially use this as the basis for key REPL statements such as update-table.

Generally speaking things will resolve down to named symbols that identify them based on label's provided by the DM or by the REPL on behalf of players. This maybe makes adding important creature comforts like code-completion and font-lock easier to support.

Author: Corwin Brust

Created: 2019-12-25 Wed 08:37

Validate