README Enhancement - Equivalent Python Syntax Examples

[jim-hart]

Who doesn't love an excessively detailed README? Can you really resist the urge to put in a sweet table of continents?

The README by itself isn't lacking in respect to what it does or what it tries to accomplish. Unfortunately, because of how Screeps handles certain methods and objects, finding a python syntax that fits can be confusing at first. This isn't anyone's fault, it's just the nature of writing Python code that will be translated to equivalent JavaScript for a specific program.

The idea for this came from doing the tutorials where it was initially hard to find a way to write some expressions in Python that would accomplish what the tutorial was asking me to do (like passing a filter expression as an optional argument). The slack channel was immensely helpful helpful though, and after asking a few questions, it was immediately clear there is usually a way to create similar Python code. However, because the message history for the #Python channel goes back only a few days, there is no record of the questions asked (or the answers).

To help those new to Screeps who want to write their code in Python, I think a mini-guide of sorts containing Python equivalent code of common Screeps idioms and code usage. It wouldn't cover every conceivable case, just how to accomplish some of the more complex features Screeps offers using Python syntax.

I'd like to start working on a rough draft for this idea, but wanted to get feedback before I put anything together to see if it would be fitting for the project itself.

[daboross]

This does seem like a good idea. Sorry I missed the issue earlier!

If you want to reopen this, I'd be in support of that.

[jim-hart]

@daboross - With PR #8 up, I didn't to add another one to your workload. I'll open this back up a few days after #8 is finalized.

[jim-hart]

Finally getting around to this; I figure the following are worth covering:

1. Working with the API
   • Basically, what changes have to be made in your Python code to use most API calls.
2. Lodash
   • A basic overview of the library and some examples of common lodash calls like _.filter(), _.max(), and son on.
3. JavaScript method usage:
   • A small list of some useful core JavaScript methods that cover the Python functionality not available through Transcrypt. For example, how .includes() or .indexOf() can be used to do what the Python's in operator accomplishes.
4. Odds & Ends:
   • More specific concepts that don't really fit in any of the above categories. Showing the Python version of PathFinder making a CostMatrix call (the one provided in the API as ab example) would cover how to actually use the roomCallback arg in Python, and it would would touch on constructs like __new__()

Open to any feedback about parts I should leave or, or concepts I should either add, or expand on.

[daboross]

These seem like good things to have. Do you think it would be better to provide these as small, separate examples, or something more integrated?

I can imagine a few different formats we could do this as, like an FAQ, a guide from "I know python" to having built a fairly minimal AI, or just making a very commented example AI.

I think you have everything we'd want to cover covered. I can help out providing details and/or writing things if we decide on a format we want. gitbook.com also provides hosted pages which are generated from md files in the repository, if we want to go that route - it's slightly nicer than raw github pages.

[jim-hart]

I think a combination of separate examples and something integrated would work well. I referenced the example code you provide with the project a lot when I first started; it helped out a lot so you could keep as is, or it could be expanded to include some of the examples directly. We could also write a new one if you prefer something like that.

I think gitbook would work great for this, standard .md files do the job, but something with a bit more substance would be nice for documentation like this.

I didn't have any set format in mind beyond providing examples and going into detail about what's going on in the example when needed. My experience is more with writing project overviews, so if you think a specific format would work best, I'm fine with that.

[daboross]

Cool- I don't have much of a preference either.

For gitbook, my understanding is that it can really just be plain .md files in a book/ directory, and they will automatically be published as a book as well - all that's needed is a SUMMARY.md file with links to everything. The "book" could just be a selection of FAQ and examples, too, so it doesn't have to be anything special. It would just be under a nice website rather than being rendered in github.

If you have an idea of an overview, I'd say go for it. I can fill in anything needed. I doubt any structure I can come up with would be better than yours.

[jim-hart]

I went with the API/Documentation format through gitbook; I checked out some examples, and it seems to give enough freedom to provide general summaries in addition to syntax examples that are easily accessible through the sidebar.

You should have have administrative access to the book; once you accept the initial invite, I'll transfer ownership to you.

[daboross]

What would you think of having the book associated with this git repository, so that changes could be submitted as pull requests?

I've finally gotten some time to look at the book, and it does look pretty nice. Would you be alright with my just adding it as a book/ folder here and linking to it in the README? We can definitely add more sections and flush out things after this too.

[jim-hart]

Yeah, that sounds like a good idea, keeping everything centralized to the project repo would be easier. Gitbook also never responded to my ticket in regards to me not being able to transfer ownership to you, so this would fix that as well.

[daboross]

Alright - git book is published as part of the repository! I've added you as collaborator in GitBook as well.

[jim-hart]

Awesome, thanks for the collaborator status as well; I'll limit contributions to more comprehensive updates to prevent cluttering the commit log unless you have another preference.

[daboross]

Works for me!

[magnes3d]

Hey guys I need some help and I am not really sure where to get it from. I have been searching and trying to figure out a way to use Screeps for my Classroom. I am a 7th/8th grade coding teacher. This is a very new program at the school where I am hired and they have tasked me with teaching my students how to code. Long story short I would like to use the game Screeps to help my students.

I would like to teach them how to code Python. However the game uses JS. I have found that you guys have created an API to help make this possible. However I have very little clue as to how this would work.

I am lost as to how to install it and exactly how to get it rolling. I think I may have gotten it installed using 'pip'?!?! but I have no idea what I am doing. I don't know if it actually makes it where typing in the game python is used, or if I have to type it in python, then translate it, then copy it to the screeps game and run it.

Have you guys created any YouTube videos demonstrating how this stuff works, or it working at all? I am entirely new to the game Screeps, but I would really like to learn how to play and how to teach my students to play.

If I could be walked through the process even one time I could make a how to for you guys. Read me's are great and all, but to someone as new as me. Putting this all together is very tricky and time consuming, when I think it probably is not necessarily the case.

[daboross]

magnes3d Thank you for your interest!

There aren't currently any videos, but we've been trying to keep the book up to date with instructions. There are some good videos covering the game in general and using JavaScript, but using python for screeps is niche enough that I think we're the only real central resource.

For "how the code gets in", it is indeed first translated locally and then uploaded. The build.py tool in this repository can automatically upload the translated code given a username and password entered into config.json, but it does require using a local editor.

I think it'd be cool to learn python with this repository! You should know that there are some differences between the "python" transcrypt accepts and regular python. All the syntax is the same, but not very many python standard libraries exist in transcrypt, and there are a few other differences noted here.

If you have more questions, we could chat in '#python' on the screeps slack. I might not be active when you come in, but other people using this repository frequent that channel as well. The screeps chat is generally the most active community for the game, and people there are definitely willing to help with things like this.

---

Sidenote: not python, but I've heard th_pion's screeps videos are quite good for general game knowledge.