Designing a Model

One of the guiding principles of Querki is that it should take less time to get your Space up and running than it takes to figure out what your data looks like. Here's a quick illustration of creating a Model. This looks long, mostly because of all the images, but it takes a lot less time to do than to read, and we're going to cover an enormous amount of ground on this page. This one is really the heart and soul of building Spaces in Querki.

To start building The Subway Game, we're going to introduce the concept of Archetypes. This is a favorite technique of mine in game design: each Archetype is a little nugget, a piece of a character, but not one that's fully-fleshed-out. I like to build a lot of these, stream of consciousness. But first, I need a Model for them.

To begin creating a Model, I go to the Actions menu, and choose "Design a Model":

That brings up the Design a Model dialog:

This dialog lets me choose which Model our new one is going to be based on. 95% of the time you can ignore this, and just leave it as Simple Thing -- sub-Models are a fairly advanced topic. So I simply press "Create Model", and it takes me to the Model Designer:

Up at the top, it says "Designing Model .3y286eu", which looks a little odd, but that's because this Model doesn't have a name yet: it wants to show something, so it instead shows the new Model's Object ID. Object IDs, or OIDs, are discussed later, under Advanced Topics -- for now, suffice it to say that every Thing in Querki has a unique OID, and it is used when the Thing doesn't have any other Name.

The Model Designer is divided into two sections, Instance Properties and Model Properties. Instance Properties are the ones you might want to set for each Instance, so they show up in the Instance Editor. Model Properties are the ones that you expect to be the same for all Instances of this Model. As you see, for a Model based on Simple Thing, we start out with the Display Name in Instance Properties -- each Instance has its own name -- and the Default View (which will be discussed later) is the same for all Instances.

I fill in the Display Name to name my Model:

Note that the Model Designer, like the Instance Editor, auto-saves everything as soon as you tab or click outside that field.

Now, let's add some Properties to Archetype. To begin with, I want a quick one-line description of what this Archetype is about. Conveniently, Querki has a built-in Property named "Summary", which is more or less what I want. So I click on the "Add a Property" button, and it gets replaced by the Add Existing Property panel:

From the drop-down, I choose the "Summary" Property:

Note that the drop-down is divided into "Properties in System", followed by "Advanced Properties in System". For now, don't worry about the Advanced Properties -- as it says, they're Advanced, and you don't need them for ordinary work.

Having selected Summary, I press the "Add" button, and the Summary Property appears in my Instance Properties:

That initially contains four underscores, which is QText shorthand for "insert a link to this Thing". That's not what we want in our case, so I simply delete those:

Don't be afraid of changing stuff like this. Querki often starts new Properties off with default values, so that they do something sensible even if you don't set them. But you're not obligated to leave those defaults in place -- change them as makes sense to you.

Okay, that's one Property. Now, let's add Rating -- a Property that lets me rate Things with stars -- so that I can keep track of how interesting I think this Archetype is for the game. Again, I go into Add Existing Property, and select Rating from the drop-down:

Note that, when I select a Property from the drop-down, it displays the documentation for that Property. This is a quick and easy way to skim through the available Properties, and see what you might want to use. I press the Add button, and Rating shows up in my Instance Properties.

Now I want a Property to actually write the guts of the Archetype. I could use the built-in Details Property, but let's say that I want my own Property that has the connotation of "stuff that only GMs get to see". We'll call it Notes.

To create Notes, from the Add Existing Property panel I press the "Create a New Property instead" button:

The Add Existing Property panel gets replaced with the Create New Property panel:

This is where I give the basic information about the new Property: its Name, its Collection and its Type. We'll talk about Collections and Types later; for now, suffice it to say that we'll make it an Optional Large Text Property:

I press the "Create" button, and the new Notes Property shows up in the Instance Properties:

Notes showed up with a bunch of stuff beneath it. That is the Property Editor, the way that you tweak the details about a given Property, and it shows up automatically when you create a new Property. (You can get to the Property Editor from any Property in the Model Designer, by clicking on its name.) The Property Editor lets you edit "meta-Properties" -- Properties of Properties -- and displays the meta-Properties that seem to be relevant for this Property. This always includes Summary and Details, which let you document what this Property is for, and any additional information about how to use it. This is totally optional, but if your Space is going to be used by multiple people, or is going to be complicated, it's often worth filling them in to remind yourself later. Since this is a Large Text Property, this also allows you to set the minimum legal length for values of this Property. I don't care about any of that right now, so I just press "Done" to make the Property Editor go away.

Okay, that's enough designing for now. What does the result look like? I press the "Done" button at the bottom of the Model Designer, and get the page for my new Archetype Model:

Does it work? I press the Create Instance button () button at the top, and it shows me the Create Instance page, just the same as it did in the last section when I was creating Instances of Game:

I fill that in:

I press Done, and I have an Archetype:

Hmm. I'd really prefer to have the Rating at the bottom of the Instance Editor, since it's the least important field. Fortunately, it's easy to rearrange the fields. From my Spy, I click on "Archetype" in the subtitle (remember, there's usually a link in the subtitle from the Instance to the Model), and from the Archetype Model I press the Edit button () to get back to the Model Designer.

All of the Properties in Model Designer can be rearranged by drag-and-drop. (You can also drag from Instance Properties to Model Properties, if you don't want a Property to be editable in each Instance.) I drag Rating down to the bottom of the Instance Properties, so they come out like this:

I press "Done". Now I want to see what my Spy looks like. That's why, at the bottom of each Model, it lists all of the Instances of that Model:

I click on Spy, press the Edit button on that, and I see that the Instance Editor has been rearranged the way I want it:

Okay, one more detail before we finish with the Model Designer. You might have noticed in previous illustrations that there's a green version of the Edit button in the upper right-hand corner of the Instance Editor, when you're hovering over it:

That is the Advanced Editor button. If you click on it, you get taken to the Advanced Editor for that Thing:

The Advanced Editor is similar to the Model Designer: in particular, it allows you to add additional Properties to this Thing. You shouldn't need it very often, but it's occasionally a life-saver. The Instance Editor is designed to make it as quick and easy to input and edit data as possible, but is a bit limited; the Advanced Editor gives you access to the full power of Querki, for when you want to do something out of the ordinary.

That was a lot, but here are the high points:

That's pretty much it: you now know how to create your own Models, which is the heart of building a Querki Space. The rest of this section of the book will go into more detail about what you've seen here, in particular discussing the various Collections and Types, and how to make Things display the way you want. But you already know enough to start doing useful stuff with Querki.