mirror of
https://github.com/swarm-game/swarm.git
synced 2024-08-16 18:10:23 +03:00
Documentation edits in preparation for alpha release (#691)
This commit is contained in:
parent
effef86d22
commit
d0dc04a2d7
@ -112,8 +112,7 @@ the same as a bug report. Just describe your idea in as much detail as you can.
|
||||
You are very much encouraged to help think about game design: how new
|
||||
language features, entities, devices, and world features should be
|
||||
added and changed, and how they all fit together to deepen the game
|
||||
and create possibilities of gameplay. This aspect of the game is very
|
||||
much unfinished and will need a lot of work. Take a look at the
|
||||
and create possibilities of gameplay. Take a look at the
|
||||
[DESIGN](DESIGN.md) document in this repository for some overarching
|
||||
thoughts and principles about the design of the game.
|
||||
|
||||
@ -237,8 +236,7 @@ suggestions.
|
||||
hand. PRs will be merged as a single squashed commit, using the
|
||||
title and description of the pull request, so make sure that they
|
||||
give a good overview of the content of the PR. To merge a pull
|
||||
request, (1) make sure it has at least one approving review, and
|
||||
(2) add the `merge me` label.
|
||||
request, just add the `merge me` label.
|
||||
|
||||
More conventions will be added as we think of and/or come up with
|
||||
them!
|
||||
@ -268,8 +266,9 @@ fixed up later if necessary, and it's more important to help them feel
|
||||
welcome and that their contribution is valued. More experienced
|
||||
contributors can be held to a higher standard.
|
||||
|
||||
Having push access also means, of course, that you can push directly to
|
||||
`main`. You are welcome to do so for typos, small fixes, documentation
|
||||
improvements, and the like; for larger fixes, new features, _etc._ opening a
|
||||
pull request from a feature branch is still preferred, to give a chance for
|
||||
others to offer suggestions for improvement.
|
||||
Having push access also means, of course, that you can push directly
|
||||
to `main`. You are welcome to do so for typos, small fixes,
|
||||
documentation improvements, and the like; for larger fixes, new
|
||||
features, _etc._ you should still open a pull request from a feature
|
||||
branch, to give a chance for others to offer suggestions for
|
||||
improvement.
|
||||
|
79
DESIGN.md
79
DESIGN.md
@ -1,36 +1,55 @@
|
||||
A few principles to guide the development and design of the game.
|
||||
Here are a few general guiding principles behind the development and
|
||||
design of the game.
|
||||
|
||||
- Above all, the game should be fun! (But it's OK if it's only fun to
|
||||
a certain kind of nerd.)
|
||||
Fun
|
||||
---
|
||||
|
||||
- The game is, first and foremost, a *programming* game, and it should
|
||||
promote the exploration and use of various sorts of programming
|
||||
abstractions. In other words, it should reward finesse in writing
|
||||
sophsticated robot programs, as opposed to e.g. throwing a ton of
|
||||
robots at things by brute force (though it's OK if some brute force
|
||||
is required as well).
|
||||
The game should be fun! (But it's OK if it's only fun to a certain
|
||||
kind of nerd.)
|
||||
|
||||
- There should be multiple viable paths to upgrading and building more
|
||||
abstractions. In other words, we *don't* want a linear chain of
|
||||
achievements, where you *must* enable language feature X in order to
|
||||
obtain resource Y, which you need in order to enable language
|
||||
feature Z, which you need in order to... and so on. Some of this
|
||||
will probably happen organically---it would probably be impossible
|
||||
to enforce a strictly linear chain of achievements even if we wanted
|
||||
to---but it's worth reflecting on explicitly.
|
||||
Programming
|
||||
-----------
|
||||
|
||||
- Ideally, everything in the game---including both entities and
|
||||
programming language features---should be discoverable just by
|
||||
playing. (This includes the possibility of having an in-game
|
||||
tutorial to teach the basics first.)
|
||||
The game is, first and foremost, a *programming* game, and it should
|
||||
promote the exploration and use of various sorts of programming
|
||||
abstractions. In other words, it should reward finesse in writing
|
||||
sophsticated robot programs, as opposed to e.g. throwing a ton of
|
||||
robots at things by brute force (though it's OK if some brute force is
|
||||
required as well).
|
||||
|
||||
- The activities of adding more programming language features, adding
|
||||
new kinds of entities and recipes, and adding new things to the
|
||||
generated worlds are all inextricably linked, and should be done
|
||||
deliberately. It will probably require a lot of experimentation and
|
||||
tweaking to balance things so that gameplay is interesting and
|
||||
challenging but not overly difficult.
|
||||
Composability
|
||||
-------------
|
||||
|
||||
- Don't provide complex built-in features; instead, provide simple,
|
||||
fundamental, composable pieces out of which users can build the
|
||||
complex features themselves.
|
||||
Don't provide complex built-in features; instead, provide simple,
|
||||
fundamental, composable pieces out of which users can build the
|
||||
complex features themselves.
|
||||
|
||||
Open World
|
||||
----------
|
||||
|
||||
There should be multiple viable paths to upgrading and building more
|
||||
abstractions, and multiple avenues for exploration. In other words,
|
||||
we *don't* want a linear chain of achievements, where you *must*
|
||||
enable language feature X in order to obtain resource Y, which you
|
||||
need in order to enable language feature Z, which you need in order
|
||||
to... and so on. Some of this will probably happen organically---it
|
||||
would probably be impossible to enforce a strictly linear chain of
|
||||
achievements even if we wanted to---but it's worth reflecting on
|
||||
explicitly.
|
||||
|
||||
Discoverability
|
||||
---------------
|
||||
|
||||
Ideally, everything in the game---including both entities and
|
||||
programming language features---should be discoverable just by
|
||||
playing.
|
||||
|
||||
Balance
|
||||
-------
|
||||
|
||||
The activities of adding more programming language features, adding
|
||||
new kinds of entities and recipes, and adding new things to the
|
||||
generated worlds are all inextricably linked, and should be done
|
||||
deliberately. It will probably require a lot of experimentation and
|
||||
tweaking to balance things so that gameplay is interesting and
|
||||
challenging but not overly difficult or tedious.
|
||||
|
57
README.md
57
README.md
@ -12,7 +12,7 @@ complex programs.
|
||||
|
||||
![World 0 after scanning a tree and making a log.](images/tutorial/log.png)
|
||||
|
||||
The implementation is still in an early stage, but these are some of the (planned) features:
|
||||
Features include:
|
||||
|
||||
* Practically infinite 2D procedurally generated worlds
|
||||
* Simple yet powerful programming language based on the polymorphic
|
||||
@ -30,16 +30,14 @@ The implementation is still in an early stage, but these are some of the (planne
|
||||
without worrying about collecting resources.
|
||||
- There are also challenge scenarios where you attempt to program
|
||||
robots in order to solve pre-designed puzzles or challenges.
|
||||
- Future versions might also have multiplayer modes, with co-op or
|
||||
PvP play over a network...?
|
||||
|
||||
Installing and Playing
|
||||
======================
|
||||
Installing
|
||||
==========
|
||||
|
||||
Warning: Swarm is still in an early stage; it's missing many of the
|
||||
planned features, there is no winning condition, and the gameplay is
|
||||
not very deep yet. But you can program cute little robots, and hey,
|
||||
that's all that really matters, right?
|
||||
Instructions for installing from a binary release will go here!
|
||||
|
||||
Installing from Source
|
||||
----------------------
|
||||
|
||||
**NOTE**: Swarm requires a POSIX-style environment that supports
|
||||
`terminfo`. On Linux and OSX, the below instructions should work
|
||||
@ -47,7 +45,7 @@ natively. On Windows, see [the comments on this GitHub
|
||||
issue](https://github.com/swarm-game/swarm/issues/53) for instructions
|
||||
getting it to work under the Windows Subsystem for Linux.
|
||||
|
||||
The recommended way to install Swarm at the moment is as follows:
|
||||
To install Swarm from source:
|
||||
|
||||
1. Clone the Swarm repository, e.g.
|
||||
|
||||
@ -75,36 +73,19 @@ The recommended way to install Swarm at the moment is as follows:
|
||||
1. Have fun!
|
||||
|
||||
|
||||
Programming swarm
|
||||
=================
|
||||
Configuring your editor
|
||||
=======================
|
||||
|
||||
Your base has a dictionary to store definitions, like this one:
|
||||
|
||||
```
|
||||
def moveUntil : cmd bool -> cmd () = \predicate.
|
||||
res <- predicate;
|
||||
if res {
|
||||
noop
|
||||
} {
|
||||
moveUntil predicate
|
||||
}
|
||||
end
|
||||
```
|
||||
|
||||
<sup>The indentation is not required but `;` is, as it is similar
|
||||
to Haskell `>>` - that is the command monad, which imperative
|
||||
programmers can ignore. :wink:
|
||||
</sup>
|
||||
|
||||
This allows you to program robots to perform complicated tasks.
|
||||
|
||||
While you can write commands and definitions like the one above
|
||||
in the REPL, swarm also has a editor support with highlighting
|
||||
and LSP integration:
|
||||
Although you can write commands and definitions directly in the Swarm
|
||||
REPL, once you get beyond the basics you'll probably want to use an
|
||||
external editor for writing Swarm programs. Swarm has support for
|
||||
external editors with highlighting and LSP integration:
|
||||
|
||||
![Editor with problem popup](images/editor.png)
|
||||
|
||||
See the `editors` folder for details on how to configure your editor.
|
||||
Currently, Emacs and VS Code are officially supported, but more can be
|
||||
added.
|
||||
|
||||
Community
|
||||
=========
|
||||
@ -115,6 +96,6 @@ others in the community.
|
||||
If you want to contribute, you're most welcome! There are *lots* of
|
||||
ways to contribute, regardless of your Haskell background. For
|
||||
example, even someone with no Haskell experience whatsoever could
|
||||
still help with *e.g.* game design, playtesting, and level design for
|
||||
challenge mode. Check out the [CONTRIBUTING](CONTRIBUTING.md) file
|
||||
for more specific information about how to contribute.
|
||||
still help with *e.g.* game design, playtesting, and creating
|
||||
challenges and scenarios. Check out the [CONTRIBUTING](CONTRIBUTING.md)
|
||||
file for more specific information about how to contribute.
|
||||
|
Loading…
Reference in New Issue
Block a user